Introduction
Every API you've shipped was designed for a human reading docs. Agents don't read docs — they load your tool schema into a context window each call, then burn tokens guessing which endpoint to try. Take a clean REST accounting API with great human docs; point an agent at it with all endpoints exposed, and it flounders. Treating tool definitions as a product surface — scoped, named for intent, with agent-friendly errors — turns "bad agent" into "good API."
Why this matters
- Agents pay context tax for every tool you expose, whether they use it or not.
- Endpoint names that read well in docs may not parse semantically for an agent.
- Errors are how agents learn what to retry; cryptic errors waste loops.
- Tool schemas are read by LLMs more often than by humans; treat them with the same care as your public docs.
Core concepts
Surface area scoping
Don't expose all 200 endpoints; expose the 10 the agent actually needs for its role. Scoping is a feature, not a limitation.
Naming for intent
"create_invoice" beats "POST /v1/inv". The schema name is the agent's primary signal; pick it like you're writing a function name in production code.
Structured errors
Errors should tell the agent what went wrong, what to try next, and whether retry is safe. JSON over prose; codes over strings.
Tool versioning
Tool schemas are interfaces; treat them like APIs. Version, deprecate, support sunsets. Agent code drifts as schemas drift.
Practical patterns
Role-scoped tool sets
Each agent role gets a curated set of tools, not the full inventory. Reduces context bloat and confusion.
Action-oriented names
Verb-noun patterns ("send_invoice", "list_customers"). Avoid HTTP-method jargon in tool names.
Idempotency keys
Agents retry. Idempotency keys turn retry storms into single effective operations.
Error → recovery hint
Every error includes a "what should I do next" field aimed at the agent.
Pitfalls to avoid
- Auto-generating tool schemas from REST docs without curation.
- Tool descriptions that say "see API reference" — the agent can't click.
- Errors that leak internal stack traces; agents will faithfully include them in user-facing output.
- No schema validation on agent-supplied inputs; the API absorbs garbage.
Key takeaways
- 1Tool schemas are a product surface. Design them.
- 2Scope, name, and document for the LLM consumer.
- 3Make errors actionable; agents learn from them.
- 4Version your tool inventory like your public API.
Go deeper · external resources
Curated reading list to take you from primer to practitioner. All links are external and free to read.