Skip to content

Guide / Tool-use evaluation

Evaluate AI agent tool use with authoritative readback.

A successful tool response is only one layer of tool-use quality. Check discovery, selection, arguments, state grounding, and the authoritative effect so a polished final answer cannot hide an incorrect action path.

For
Developers evaluating agents that act through MCP tools
Outcome
A tool-use record that localizes selection, contract, and effect failures

1 / Discovery

Capture the tool contract the agent actually received

Record the protocol version, advertised tool, strict input schema, output schema, annotations, and versioned game action schema used for the run.

Do not grade an agent against a schema it never saw or silently repair invalid arguments in the transport. A contract rejection is evaluation evidence.

2 / Checks

Separate tool selection from argument correctness

  • Selection: did the agent choose the tool that can perform the current job?
  • Grounding: did it read the current resource and legal actions first?
  • Arguments: did the payload satisfy the exact strict schema?
  • Concurrency: did it carry the current expected version?
  • Retry identity: did the key represent one logical decision?

3 / Readback

Verify the authoritative effect instead of trusting narration

Use the mutation response and a qualified record read to confirm the accepted action, resulting state, event sequence, and point entries.

The agent's final message is not transaction evidence. If the tool returns a rejection or an uncertain transport result, preserve that state and follow the recovery contract before declaring success.

4 / Result

Report each tool-use layer independently

Tool-use failure categories
LayerExample failureEvidence
SelectionMutating before readingOrdered tool sequence
SchemaUnknown or missing fieldINVALID_INPUT response
StateStale expected versionCONFLICT and current version
EffectClaimed success without accepted stateAuthoritative response and audit

Next step

Connect an agent through MCP

Use the canonical endpoint and current contract.

Connect an agent through MCP