# Tools decide what an agent can do An agent can only act through its tools, and it only understands them through their descriptions. Good tools are few, clearly named, short in what they return, and honest about errors. ## The edge of the agent is the edge of its tools The model only produces text. Anything it does to the world, reading a file, running a test, creating a calendar event, happens because the harness offered it a tool and the model chose to call it. No tool for it means no way to do it, however capable the model is. So the tool list is a design decision with the same weight as the prompt. Anthropic's advice in "Building effective agents" is blunt about it: tools deserve as much prompt-level effort as the instructions do. The model also never sees your code. It sees a name, a description and a list of parameters, and it guesses from those. A tool is only as good as the words that describe it. ## What a good tool looks like Anthropic's tool-writing guide collects the habits that worked. They read as small, boring choices, and each one removes a way for the agent to go wrong. - **Fewer, broader tools.** One `schedule_event` tool beats separate tools to list people, check availability and create the event. Every extra tool is one more thing to choose between. - **Names that group.** A prefix such as `asana_search` tells the model which service a tool belongs to. - **Answers a person could read.** Return names, not UUIDs. An opaque identifier gives the model nothing to reason about. - **Mistake-proof arguments.** Anthropic's SWE-bench work required absolute file paths, so the agent could not get a relative path wrong. - **Errors that say how to fix.** "Invalid input" sends the agent into guessing. A message that names the missing field lets the next step be correct. ```flow Prototype the tool Run realistic tasks that need several calls Read the transcripts for confusion Rewrite the name, description or output Run the same tasks again ``` That last loop is the one worth copying. Judge a tool by watching an agent use it on real work, tracking runtime, number of calls, tokens and errors. Description changes alone were enough to reach state of the art on SWE-bench Verified. **Question:** Your agent keeps passing badly formed file paths to a tool. What is the better fix? - Add a paragraph to the system prompt reminding it to be careful - Change the tool so it only accepts absolute paths - Switch to a larger model - Remove the tool **Answer:** Change the tool so it only accepts absolute paths. Making the mistake impossible beats asking the model not to make it. Anthropic's SWE-bench work did this by requiring absolute paths. ## Output is paid for in context Everything a tool returns goes into the context window, and the model reads all of it on every later step. A tool that dumps a whole table costs you on each turn that follows. The guide's answers are practical. Offer a concise and a detailed mode: the concise one used about a third of the tokens. Paginate and truncate: Claude Code caps a single tool output at 25,000 tokens. In the compiler project, test output was kept to a few lines and the detail was written to files the agent could open if it needed them. The same logic goes further with code. In Anthropic's code execution write-up, loading every tool definition and passing every intermediate result through the model wasted context. Presenting MCP servers as code the agent loads on demand took one example from about 150,000 tokens to 2,000, which is 98.7% less. A 10,000-row sheet can be filtered in code and only five rows shown to the model. > **It is not free** That approach needs a sandbox, resource limits and monitoring. Fewer tokens is a trade for more infrastructure to run. ## Restricting tools is also a design A tool you withhold is a guarantee. In Claude Code you can give a review subagent only `Read`, `Grep` and `Glob`. That limit is enforced by the harness, so the reviewer cannot edit a file even if it wants to. A line in the prompt asking it to behave is a request. A missing tool is a fact. > **Agents can fix their own tools** In Anthropic's multi-agent research system, a tool-testing agent rewrote tool descriptions, and task time dropped by 40%. > **Read your own tool list** Open a session and look at what tools Claude Code has. Pick one and imagine you only had its name and description. Would you know when to use it and what you would get back? **Question:** Why does a tool that returns a huge result hurt the agent beyond that single call? - The harness refuses further calls - The result stays in the context and is read again on every later step - The model forgets the tool exists - It makes the tool description invalid **Answer:** The result stays in the context and is read again on every later step. Tool output joins the context window. Long output uses up the attention budget and costs tokens on every following turn.