Crabhaus

What it is

Tool design is the craft of writing the schemas an agent sees — names, parameters, descriptions, and response text — so a probabilistic model reliably picks the right tool and calls it correctly. A tool is a contract between deterministic software and a non-deterministic caller, so its schema reads less like an API spec and more like documentation for a very literal new teammate.

How it works

The model only perceives what the schema exposes. Naming carries most of the weight: grouped prefixes like asana_projects_search identify the service, and unambiguous parameters (user_id, never just user) prevent wrong-argument calls. Then granularity: a few consolidated tools matched to real workflows beat dozens of thin wrappers — each extra description costs context and adds wrong-choice risk.

A concrete example

Anthropic reports schema wording alone moves benchmarks: refined tool descriptions helped Claude Sonnet 3.5 reach state-of-the-art on SWE-bench Verified, and replacing UUIDs in responses with readable names cut retrieval hallucinations. Its web-search tool once degraded results because the model kept appending a year to queries — fixed by rewording the description, not the code.

Why it matters

Many agent failures are schema failures: the wrong tool picked, a parameter guessed, context flooded by a verbose response. Tool design is the cheapest reliability lever a team has — no retraining, no framework swap — and it compounds as MCP servers pile hundreds of third-party tools into one context window. Responses are prompts too: a good error message states exactly how to fix the next call.