← Back to all products

Agent Tool Schema Design Patterns

$39

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.

11 filesv1.0.0 (updated 2026-08-02)
MarkdownTypeScriptJSONLLMOpenAI

File Structure 11 files

agent-tool-schema-patterns/ ├── GUIDE.md ├── LICENSE ├── README.md ├── examples/ │ ├── annotations.ts │ ├── described.ts │ ├── flat-vs-nested.ts │ └── idempotent.ts ├── package.json └── src/ ├── result.ts └── validate.ts

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.

Code Sample .ts preview

src/result.ts /** * result.ts — a stable result contract for tool outputs. * * Agents parse tool results. Free-text errors ("something went wrong") force the * model to guess. Structured results with stable `code`s let it branch reliably. */ export interface ToolOk<T> { content: { type: 'text'; text: string }[]; structuredContent: T; } export interface ToolErr { content: { type: 'text'; text: string }[]; isError: true; structuredContent: { error: { code: string; message: string; details?: Record<string, unknown> } }; } export function ok<T>(data: T): ToolOk<T> { return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }], structuredContent: data }; } export function fail(code: string, message: string, details?: Record<string, unknown>): ToolErr { const body = { error: { code, message, ...(details ? { details } : {}) } }; return { content: [{ type: 'text', text: JSON.stringify(body) }], isError: true, structuredContent: body }; } /** Stable error codes worth standardizing across all your tools. */ export const CODES = { BAD_INPUT: 'bad_input', NOT_FOUND: 'not_found', RATE_LIMITED: 'rate_limited', UPSTREAM: 'upstream_error', FORBIDDEN: 'forbidden', } as const;