Field guide · Tool selection
Your agent skips the tool call. Prove what the model actually received.
A tool can be healthy and still never run. Diagnose discovery, schema, runtime instructions, selection, and result handling in that order.
1. Capture the runtime tool list
Do not infer availability from source code or a local registry. Capture the names, descriptions, and schemas attached to the exact failing model request. Confirm the expected tool is present once, with the intended name and required arguments.
2. Call the tool directly
Before tuning the prompt, invoke the tool with a minimal valid payload. Verify the final side effect and output shape. If direct execution fails, the selection layer is not the first problem.
3. Remove ambiguity in the description
A strong tool description states when the tool is required, what it does, what it does not do, the minimum valid input, and what evidence it returns. Remove overlapping names and descriptions that leave two tools eligible for the same job.
4. Inspect instruction priority and conflict
Review the complete system and developer instructions delivered in the run. A safety rule, “answer directly” instruction, stale example, or broad autonomy rule can unintentionally discourage the required call. State the observable condition that requires the tool rather than merely saying the tool is available.
5. Reduce to one tool and one decision
Test a minimal prompt with only the required tool. If the model calls it, restore tools and instructions in small groups until the conflict returns. Keep the model, temperature, tool-choice setting, and input stable while isolating the change.
6. Validate argument repair and errors
Schema validation failures can look like skipped calls when a client drops the attempted call. Log structured validation errors, keep required fields minimal, avoid ambiguous unions, and ensure enum values are explained in the description.
7. Prove the result reaches the next turn
Match the tool result to the correct call identifier, keep it within size limits, and return a clear success or error envelope. Then assert the next agent decision uses the result rather than repeating or silently ending.
8. Make selection testable
Create a small evaluation set with required-call, optional-call, and must-not-call examples. Assert both the selected tool and the final outcome. Rerun it when prompts, models, tool schemas, or orchestration change.
Selection still inconsistent?
Submit one minimal failing trace.
Include the exact runtime tool list, prompt, attempted calls, validation output, and the result the workflow must prove.