Agent Tool Schema Design Patterns
Field guide and runnable examples for designing reliable tool/function schemas for LLM agents (MCP, OpenAI, Anthropic): descriptions, constraints, flat inputs, error contracts, annotations, and idempotency.
File Structure 11 files
Documentation Preview README excerpt
Agent Tool Schema Design Patterns
A field guide + runnable examples for designing reliable tool/function schemas
for LLM agents (MCP tools, OpenAI function calling, Anthropic tool use). Good
schemas are the single biggest lever on whether an agent calls your tool correctly.
Why schemas make or break agent tools
An agent only "sees" your tool through its name, description, and JSON schema.
If the schema is loose, the model hallucinates arguments, passes the wrong types,
or invents fields. If it's tight and well-described, the model calls it right the
first time. This pack distills the patterns that consistently reduce tool-call
failure rates.
The patterns
1. Describe every field for a model, not a human. Each parameter's description
should say what it is and how to choose a value. See examples/described.ts.
2. Constrain hard. Use enums, min/max, formats, and literal for fixed values
(e.g. quantity: literal(1)). Narrow types eliminate whole classes of bad calls.
3. Prefer flat inputs. Deeply nested objects raise error rates; flatten where
you can. See examples/flat-vs-nested.ts.
4. Return structured content + a stable error contract. Always return machine
codes ({ error: { code, message } }), never free-text errors. src/result.ts.
5. Annotate side effects. Mark read-only tools readOnlyHint: true and
side-effecting tools explicitly, so clients can gate them. examples/annotations.ts.
6. Make dangerous tools idempotent. Accept an idempotency key; identical calls
must not double-act. examples/idempotent.ts.
7. Validate at the boundary. Parse inputs with zod (or JSON Schema) before
your logic runs; reject smuggled fields. src/validate.ts.
Requirements
- Node.js 18+
- TypeScript 5+ (examples use zod; the principles apply to any schema language)
Quick start
npm install
npx tsx examples/described.ts # print a well-described schema as JSON Schema
File tree
src/
result.ts # ok()/fail() helpers — structured content + stable error codes
validate.ts # parse-at-the-boundary + reject-smuggled-fields helper
examples/
described.ts # good vs bad field descriptions (same tool)
flat-vs-nested.ts # why flat inputs beat nested ones
annotations.ts # readOnly / side-effect / idempotent annotations
idempotent.ts # an idempotent side-effecting tool
GUIDE.md # the full write-up with rationale + before/after metrics
License
MIT.
... continues with setup instructions, usage examples, and more.