How to Test AI Agent Tool Calls
Verify selection, arguments, permissions, results, retries, abstention, and side effects with separate checks.
Short answer
Create scenarios with an expected tool, expected abstention, or several acceptable paths. Assert tool eligibility, argument constraints, authorization, execution result handling, retry behavior, and final state. Include malformed responses, timeouts, denials, and duplicate-call risks.
Key takeaways
- Tool selection and argument validity are different tests.
- Correct abstention is as important as correct invocation.
- Verify side effects independently after uncertain responses.
Signs this is the problem
Start by confirming the symptom before changing prompts, models, or infrastructure.
- Any syntactically valid call counts as a pass.
- Tests omit permission-denied and timeout behavior.
- A tool result is correct but the agent misuses it later.
Step-by-step approach
- 1
Define tool contracts
Document purpose, preconditions, exclusions, schema, error behavior, side effects, and authorization for each tool.
- 2
Build decision cases
Include obvious choices, overlapping tools, missing inputs, forbidden actions, and no-tool scenarios.
- 3
Inject result conditions
Return success, empty, malformed, stale, slow, denied, and ambiguous outcomes.
- 4
Verify downstream behavior
Check how the agent uses the result, whether it retries safely, and whether final state matches the request.
What to measure
| Metric | What it measures | How to use it |
|---|---|---|
| Selection accuracy | Correct tool or abstention for the labeled intent. | Report dangerous wrong choices separately. |
| Argument compliance | Calls satisfying schema and scenario-specific constraints. | Reject valid JSON that targets the wrong resource or scope. |
| Safe recovery rate | Expected failures handled without policy breach or duplicate side effect. | Require evidence before automating retries. |
Common mistakes
- Testing only schema validation.
- Mocking every tool as a fast successful response.
- Letting the same agent grade its own call without independent evidence.
Practical checklist
- Define tool contracts: Document purpose, preconditions, exclusions, schema, error behavior, side effects, and authorization for each tool.
- Build decision cases: Include obvious choices, overlapping tools, missing inputs, forbidden actions, and no-tool scenarios.
- Inject result conditions: Return success, empty, malformed, stale, slow, denied, and ambiguous outcomes.
- Verify downstream behavior: Check how the agent uses the result, whether it retries safely, and whether final state matches the request.
Frequently asked questions
What should I do first?
Document purpose, preconditions, exclusions, schema, error behavior, side effects, and authorization for each tool
How should the result be measured?
Correct tool or abstention for the labeled intent. Report dangerous wrong choices separately.
When is the change ready to ship?
Ship only after the protected cases pass, the primary metric clears its agreed boundary, and the team reviews the remaining failure modes instead of relying on one aggregate score.