Agent Tool Schema Design Patterns

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

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.

... preview truncated, see full README in product download.