필사 모드: Tool Surface Design — One Schema Line Moves the Success Rate

• We added tools and the success rate went down
• The curse of tool count: expose everything vs curate
• Names and descriptions are the interface
• Parameter design: block mistakes structurally
• How to hand failure back
• The response is surface too: token efficiency
• Tools are evaluation subjects too
• Practice it yourself
• References

We added tools and the success rate went down

Say you attach five more tools to an agent and the task success rate goes down instead of up. It is a constructed example, but the direction will be familiar to any team that has widened a tool surface. The reason is two-layered: tool schemas eat the context budget every turn, and the more similar tools there are, the shakier the selection gets. Making the model capable of more things and making it finish this task better are different problems.

That is what makes tool surface a useful phrase: the design object is not each tool but the entire interface the model faces. Anthropic's agent-building guide calls this the agent-computer interface and recommends investing in it the way you invest in a human UI. The retrospective note that their own SWE-bench work spent more time optimizing tools than the prompt shows how much weight that advice carries.

The curse of tool count: expose everything vs curate

The first decision is the count. Exposing every tool you have is easy to set up, but the schemas alone shrink the budget and mis-selection between similar tools grows. The alternative — curating only what this task uses — should be the default for most work. With extra capacity, there is a further option: build one purpose-built tool for this task and add it on top. A purpose-built tool costs building and maintenance, but collapses several calls into one.

The consolidation that Anthropic's tool-writing guide recommends is the same line of thought. Instead of separate tools for listing users, listing events, and creating an event, ship one schedule-an-event tool that handles those steps internally. When the tool count drops, schema cost, mis-selection, and call round-trips drop together.

Names and descriptions are the interface

The model never sees your code; it sees names and descriptions. That is why one description line changes behavior. The same guide recommends namespacing — grouping names by service and by resource. When prefixes carry the affiliation, as in asana_search and jira_search, the model confuses similar search tools less.

# Bad — the model has to guess what this is and when to use it
- name: proc2
  description: 'process util'

# Good — when to use it, and when to use something else, are in the description
- name: code_search_symbol
  description: 'Find where a symbol is defined in the repo. For full-text search, use code_grep.'

The standard for a good description is the onboarding document you would hand a new hire: what the tool does, when to use it, when not to, and what the return looks like. As descriptions improve, the paragraphs of your prompt that explained tool usage disappear.

Parameter design: block mistakes structurally

Design parameters to shrink the places where the model can be wrong. The Anthropic agent guide compares this to poka-yoke in manufacturing: instead of correcting mistakes, build a structure in which the mistake cannot be made. A parameter that accepts both relative and absolute paths, for example, becomes an error source the moment the working directory changes; narrow it to absolute paths only and that whole class of mistakes disappears structurally. Identifiers are the same story. The tool-writing guide observes that letting the model handle human-readable names instead of opaque UUIDs raises its accuracy.

How to hand failure back

Tools fail. The design object is not the failure itself but the format in which it returns to the model. Hand back the raw exception string and stack trace, and the model tends to repeat the same call without knowing why it failed. Hand back the cause plus the alternatives currently available, and the next call is different.

{
  "error": "file_not_found",
  "path": "src/pay/handler.py",
  "hint": "The source root of this repo is services/.",
  "try_next": ["list_dir services/pay", "code_search_symbol handler"]
}

This format is directly entangled with the retry policy covered in part 4. A retry with no cause coming back is a repeat purchase of the same failure; a retry with alternatives coming back is exploration. Fixing the failure return format comes before setting the retry cap.

The response is surface too: token efficiency

Whatever a tool returns is withdrawn straight from the context budget. So the tool-writing guide places pagination, range selection, filtering, and truncation with sensible defaults on the tool side of the ledger. A read tool that returns a 4,000-line file whole is a worse surface than one that defaults to 200 lines and accepts a range parameter. And if you truncated, the design includes saying so in the response, along with how to search more narrowly.

Tools are evaluation subjects too

A tool surface is not something you build and finish; it is something you refine through evaluation. The loop the same guide recommends is plain: build a prototype, run evaluations on realistic tasks, read the transcripts the agent leaves to find where it got lost, fix the tools, and measure again. Changing one tool description is a harness change, so it is a change that the harness fingerprint covered in part 7 must catch. And what judges which surface is better is, in the end, the evaluator — whose reliability is the subject of part 5.

Practice it yourself

In the harness engineering RPG you can plug four tool surfaces into any scenario: minimal with 3 tools, task-curated with 8, curated plus a purpose-built tool, and everything exposed at 21. Go through both the scenario where full exposure collapses under schema cost and the one where the minimal set collapses under workaround cost, and the reason curation is the default sticks with you.

• Previous in the series: The context budget — design is what you leave out, not what you put in
• Next in the series: Loop design — between infinite loops and giving up early

References

• Writing effective tools for agents — Anthropic, 2025-09-11 — namespacing, tool consolidation, meaningful identifiers, token-efficient responses, and the evaluation loop are in this post.
• Building effective agents — Anthropic, 2024-12-19 — the agent-computer interface view, poka-yoke parameter design, and the note about spending more time on tools than the prompt in SWE-bench work are in this post.
• The success-rate story at the top and the schema and failure-return examples in the body are constructed for explanation.