Foundations — Issue 50

Core Concepts

Tool Descriptions Are Contracts for a Reader That Cannot Ask Questions

By Sable Whitford— October 8, 2026

Feature image for article: Tool Descriptions Are Contracts for a Reader That Cannot Ask Questions

Developers who write great API documentation often write poor tool descriptions for LLMs, and the reason is the reader. A human who hits a gap in your docs tries something, reads the error, comes back. A model fills the gap from training data and acts on it immediately. What you leave out, it invents. The instincts that make documentation generous and readable — narrative context, implicit constraints, learning by example — are the ones that get you in trouble when the reader can't ask a follow-up question.

Core Concepts

Tool Descriptions Are Contracts for a Reader That Cannot Ask Questions

By Sable Whitford— October 8, 2026

Developers who write great API documentation often write poor tool descriptions for LLMs, and the reason is the reader. A human who hits a gap in your docs tries something, reads the error, comes back. A model fills the gap from training data and acts on it immediately. What you leave out, it invents. The instincts that make documentation generous and readable — narrative context, implicit constraints, learning by example — are the ones that get you in trouble when the reader can't ask a follow-up question.

Practical Walkthrough

Read Your Tool Descriptions Like a Model Would

By Sable Whitford— October 8, 2026

Feature image for article: Read Your Tool Descriptions Like a Model Would

You named a parameter query and described it as "Search query." You know it means a natural-language place search, not SQL. The model doesn't. It gets the tool name, the description, and the input schema, and every gap you left gets filled from token probabilities instead of project context. A 2026 study rewrote descriptions across 856 MCP tools without touching code and measured real shifts in task success. Here are three broken patterns from real MCP servers, and how to find the same bugs in yours.

Practical Walkthrough

Read Your Tool Descriptions Like a Model Would

By Sable Whitford— October 8, 2026

You named a parameter query and described it as "Search query." You know it means a natural-language place search, not SQL. The model doesn't. It gets the tool name, the description, and the input schema, and every gap you left gets filled from token probabilities instead of project context. A 2026 study rewrote descriptions across 856 MCP tools without touching code and measured real shifts in task success. Here are three broken patterns from real MCP servers, and how to find the same bugs in yours.

Further Reading

Learning to Rewrite Tool Descriptions for Reliable LLM-Agent Tool UseMeasures how rewritten descriptions hold up as tool catalogs grow past 150 options, cutting accuracy loss by 29%.

Writing Effective Tools for AI AgentsAnthropic's engineering team on eval-driven tool design, namespacing effects, and why fewer tools often win.

Quick links

Define Tools: Best Practices for Tool Definitions

Tools Are Under-Documented: Simple Document Expansion Boosts Tool Retrieval

Preparing API Documentation for AI Agent Consumption

EasyTool: Enhancing LLM-Based Agents with Concise Tool Instruction

Failure Patterns

Tool descriptions carry a hidden assumption about their reader: that the reader can look things up. A human developer who hits a vague function name opens the source file. Someone confused by a parameter checks the docs or asks a colleague. The description doesn't need to be complete because the reader has escape hatches.

A language model has none. The tool name, the parameter schema, and the description string get serialized into context, and if a fact isn't in that text, the model doesn't have it. It commits to a tool call in one shot, from what's in front of it.

That constraint turns six common description habits — shortcuts that work fine for human readers — into distinct failure modes, each with its own signature in production logs.

Failure Patterns

Tool descriptions carry a hidden assumption about their reader: that the reader can look things up. A human developer who hits a vague function name opens the source file. Someone confused by a parameter checks the docs or asks a colleague. The description doesn't need to be complete because the reader has escape hatches.

A language model has none. The tool name, the parameter schema, and the description string get serialized into context, and if a fact isn't in that text, the model doesn't have it. It commits to a tool call in one shot, from what's in front of it.

That constraint turns six common description habits — shortcuts that work fine for human readers — into distinct failure modes, each with its own signature in production logs.

Ambiguous Names

Vague Tool Names Make Models Guess Blind

A human reads fetchpd and opens the source file. A model has only the name and description in its context window — no source to check. Anthropic's engineering team recommends namespacing by service and resource (asana_projects_search over search) because ambiguous names cause selection errors that compound across multi-step workflows.

Missing Constraints

Unspecified Formats Get Filled by Model Defaults

When a parameter says date: str with no format specified, the model fills in whatever it generates most frequently. Constrained schemas — enums for fixed option sets, date-time format hints, integer instead of number — turn your unstated expectations into boundaries the model can actually respect.

Hidden Effects

Undocumented Side Effects Break a Model's Reasoning

If a file-fetch tool writes to a scratch directory and returns the path, the model needs to know that. It can't inspect the implementation. Without explicit side-effect documentation, the model treats writes as reads, retries destructive calls without hesitation, and builds later decisions on state it doesn't understand.

Overlapping Tools

Near-Duplicate Tools Tank Selection Accuracy at Scale

One benchmark measured 13% baseline tool-selection accuracy when agents faced a large candidate pool — recoverable to 43% with retrieval-augmented filtering. Attention studies show models look at the right tool most of the time and still pick wrong. Overlapping descriptions make the final decision harder than the search.