design-agent-toolslisted

# Design Agent Tools Most "the agent is dumb" reports are tool-interface bugs. Fix the interface before touching the prompt or the model. ## When this applies - Agent chooses tool B when tool A was correct - Agent never calls a tool that clearly applies - Repeated argument validation errors - One tool call floods the context - Agent calls the same tool with the same args repeatedly - Adding tools, or wrapping an existing API for an agent ## Do not use for - Building the loop itself → `build-agent-loop` - Diagnosing a specific failed run → `debug-agent-trajectory` ## Inputs to collect first | Input | Why needed | Default if unspecified | |---|---|---| | Current tool schemas + descriptions | The thing being fixed | Ask for them; do not redesign blind | | A failing trace, if one exists | Shows the actual confusion | Proceed without, but ask | | The underlying API/data source | What is actually available | Ask | | Typical user phrasings | Descriptions must match user vocabulary | Ask for 5 real examples | ## Procedure ### Step 1 — Inventory and cluster List every tool with its description. Group tools whose descriptions could plausibly answer the same user request. Every cluster of size > 1 is a selection-accuracy risk. **Stop condition:** a table of `tool → cluster` exists. ### Step 2 — Reshape around tasks, not endpoints For each cluster, ask: *what does the agent actually need to accomplish?* If answering one user question requires 3+ chained calls, collapse them