2.a.ii Rewrite the tool surface: names, schemas, descriptions

Change what the model sees of each tool without touching its implementation: a distinct name, a strict schema (enums, required fields), and a description with fixed sections (what it is for and when to use it versus sibling tools, defaults and limits, error modes, side effects), plus a usage example for complex parameters. Write for the model: distinctive terms, since search finds tools by them; error messages that say what to do next. One rewrite fed the misrouted cases matches hand-tuning; richer descriptions add steps, so slim them after. Where two tools genuinely overlap, rewording cannot separate them: consolidate instead (2.a.i).

Tier 1 because when the hand-labeled set shows behavior unchanged.

When it applies

In the code: descriptions that do not state the tool's purpose (56% of audited MCP tools) or when to use it; duplicate or overlapping names; schemas without enums or required fields; no example for complex parameters
In traces: misrouted cases per tool (false positives and false negatives); failure rows labeled incorrect-tool-selection, malformed-arguments or suboptimal-arguments; per-tool error rate and retries (Datadog tracks these per tool and server)
In eval results: failures attributed to tool selection or arguments; step count per task after a description change

How

From traces, collect misrouted cases per tool (called when it should not have been, and not called when it should).
Audit descriptions for missing purpose, missing when-to-use, and duplicate names.
Rewrite once with an LLM, given the misrouted cases; add a usage example for complex parameters.
Slim the result and check step count.
Replay the hand-labeled set, or run the paired eval; pairs that stay confused go to 2.a.i for consolidation.

How to measure it

verify fix (tier 1): replay the hand-labeled set
experiment (tier 3): paired eval, old against new descriptions

To compare the change against your agent's current version, with the same cases and enough repeats to see past run-to-run noise, use aot-evals.

Expected impact

Quality: improves, medium: +5.85 pp median success (Feb 2026); complex-parameter accuracy 72% to 90% with examples (Anthropic); a compliant description picked 72% vs 20% among equivalents
Cost: mixed, medium: augmented descriptions added 67% more steps; slim variants keep most of the gain
Performance: mixed, small

Evidence

Evidence comes from: Tool use, Code generation, Web research.

five follow-up benchmarks

7 to 18 of 20 runs per benchmark.

Scale AI, VeRO code release · figure_01
GAIA/FACTS/SimpleQA

The Tool-Centric template is built around docstring guidance and parameter design.

Scale AI, "VeRO: A Harness for Agents to Optimize Agents" (ICML 2026) · Feb 2026 · paper Table 11
Give explicit tool-selection heuristics in the promptNot measured

"an agent searching the web for context that only exists in Slack is doomed from the start" ... "Bad tool descriptions can send agents down completely wrong paths, so each tool needs a distinct purpose and a clear description."

Jeremy Hadfield, Barry Zhang, Kenneth Lien, Florian Scholz, Jeremy Fox, Daniel Ford (Anthropic), "How we built our multi-agent research system" · Jun 2025Older evidence · Prompt engineering: Tool design and selection are critical
Use a tool-testing agent to rewrite tool descriptions

"This process for improving tool ergonomics resulted in a 40% decrease in task completion time for future agents using the new description, because they were able to avoid most mistakes." (no benchmark, n or model beyond "Claude 4 models")

Jeremy Hadfield, Barry Zhang, Kenneth Lien, Florian Scholz, Jeremy Fox, Daniel Ford (Anthropic), "How we built our multi-agent research system" · Jun 2025Older evidence · Prompt engineering: Let agents improve themselves
Document each tool with When/Protocol/Errors/Side-effectsNot measured

Every tool description in the study uses this template. Not ablated.

Fan et al., "An Empirical Study of Harness Design for Coding Agents" · Sep 2026 · App 8, Figs 21-31
Rewrite and compress tool documentation for retrievalNot measured

Described as reducing token overhead and redundant calls. No numbers are quoted.

Xiaofang Yang, Lijun Li, Heng Zhou, Tong Zhu, Xiaoye Qu, Yuchen Fan, et al. (Shanghai AI Lab et al.), "Toward Efficient Agents: A Survey of Memory, Tool Use, and Planning" · Jan 2026 · §4.1 External Retriever; §4.2 Cost-Aware Tool Calling
Prefer dedicated tools over shell in instructionsNot measured

Claude Code "Do NOT use the Bash tool to run commands when a relevant dedicated tool is provided ... allows the user to better understand and review your work."

Barbaste et al., "Harness Engineering: Anatomy, Architecture, and Evolution of Coding Agents -- A Source-Code Study of Eleven Systems" · Jul 2026 · Sec 7.3 "Tool-use philosophy"
Generate tool guidance from the active toolsetNot measured

Pi "each tool contributes promptSnippet/promptGuidelines, so the prompt co-varies with the active toolset"; whole prompt is 30–40 lines.

Barbaste et al., "Harness Engineering: Anatomy, Architecture, and Evolution of Coding Agents -- A Source-Code Study of Eleven Systems" · Jul 2026 · Sec 7.2 (Pi)
Rewrite tool descriptions with a trained rewriter

StableToolBench with 150+ candidate tools: a curriculum-trained description rewriter, needing no per-tool traces, cuts the accuracy lost as the catalog grows by 29.23% and raises average query-level success by 60.89%; complementary to agent fine-tuning. Requires training the rewriter.

Guo et al., "Learning to Rewrite Tool Descriptions for Reliable LLM-Agent Tool Use (Trace-Free+)" · Feb 2026
Fix description defects: purpose, functionality and accuracy

18 description smells audited over 10,831 MCP servers; 73% have repeated tool names. Controlled mutations: functionality and accuracy defects shift selection most (+11.6%, +8.8%, p<0.001). Among functionally equivalent servers, a standard-compliant description is picked 72% of the time against a 20% baseline.

Wang et al., "From Docs to Descriptions: Smell-Aware Evaluation of MCP Server Descriptions" · Feb 2026
Augment tool descriptions, then slim themMixed

856 tools on 103 MCP servers: 97.1% of descriptions have at least one smell; 56% do not state their purpose. Augmented descriptions: +5.85 pp median success, +15.12% partial completion, but +67.46% execution steps and 16.67% of cases worse. Slimmer variants keep most of the gain.

Hasan et al., "Model Context Protocol (MCP) Tool Descriptions Are Smelly!" · Feb 2026
Rewrite descriptions once from misrouted cases

Production router (9 skills, 372 test cases) and ToolBench (16k tools): one LLM rewrite fed the false-positive and false-negative cases reaches 79.2% F1 against 79.4% hand-tuned, at 32x less effort. Iteration budget, feedback mix and training-set size each move F1 by under 0.5%.

Zhou et al., "A Single Rewrite Suffices: Empirical Lessons from Production Skill Description Optimization" · Jun 2026
Consolidate tools whose scopes genuinely overlapMixed

Same study: where two skills genuinely overlap in scope, rewording cannot separate them; the paper gives a signal for detecting such pairs, which need consolidation instead.

Zhou et al., "A Single Rewrite Suffices: Empirical Lessons from Production Skill Description Optimization" · Jun 2026
Add usage examples to tool definitions

Internal testing: examples in tool definitions raised accuracy on complex parameters from 72% to 90%.

Bin Wu et al. (Anthropic), "Introducing advanced tool use on the Claude Developer Platform" · Nov 2025
Use code mode for multi-tool tasks onlyNot measured

About 30% fewer tokens on identical tasks (one author's test, Opus 4.5); little benefit on single-tool tasks; model-dependent. A description mentioning 'long-running task' pulled in the wrong extension; explicit imports prevented it.

Rizel Scarlett (Block), "8 Things You Didn't Know About Code Mode" · Feb 2026
Choose the tool-search method by how many results the agent sees

270 tools, 2,700 queries: top-1 retrieval BM25 14%, hybrid 21%, embeddings 38%; top-5 85-90% for all three. Whether a tool is found depends on distinctive terms in its description. Retrieval only, not task success.

Guillaume Lebedel (StackOne), "Comparing BM25, TF-IDF, and Hybrid Search for MCP Tool Discovery" · Feb 2026
Write descriptions and parameters for the model; errors that say what to do nextNot measured

From building 8,000+ tools, not measured: descriptions and parameter names written for the model, lenient input handling, error messages that tell the agent what to do next, consistent response shapes, batch operations instead of one call per item.

Sattanathan, Byrro and Tahler (Arcade.dev), "54 Patterns for Building Better MCP Tools" · Feb 2026
Trace tool listing and calls, linked to the model call that chose themNot measured

Traces tools/list and call_tool, each linked to the LLM call that chose the tool; per-tool and per-server error rate, retries and p95 latency; large registries add latency. No wrong-tool or unused-tool metric. Not measured.

Lily Chen et al. (Datadog), "Gain end-to-end visibility into MCP clients with Datadog Agent Observability" · Dec 2025

Also known as

Low-friction tool input formats
Poka-yoke tool design
Tool namespacing

In Claude Code

This optimization is a skill in aot-kit, our open-source Claude Code plugin: /aot-kit:rewrite-tool-surface. Its library entry holds every source. Have new evidence, or a correction? Suggest a change.

Rewrite the tool surface: names, schemas, descriptions