Lesson 1 · 6 min

Tool Schema Fundamentals

Designing input schemas Claude reliably populates.

Claude calls tools more reliably when schemas are flat, fields are named for intent (not implementation), and descriptions cover edge cases. Prefer enums over free-form strings when valid values are bounded.

Production scenario

Real-world example: A Stripe-style refund tool

Compare two refund tool schemas exposed to the agent:

Sloppy:

{ "name": "refund", "params": { "args": "string" } }

Production:

{
  "name": "issue_refund",
  "description": "Refund a charge. Customer is notified by email automatically.",
  "params": {
    "charge_id": { "type": "string", "description": "ch_... id from the original charge" },
    "amount_cents": { "type": "integer", "description": "Omit to refund full amount" },
    "reason": { "type": "string", "enum": ["duplicate", "fraudulent", "requested_by_customer"] },
    "notify_customer": { "type": "boolean", "default": true }
  }
}

The flat, enum-constrained second schema gets near-100% valid tool calls. The first schema constantly produces malformed arguments because the structure lives in prose.

Why this matters: schema design is the single biggest lever on tool-call reliability. Flat fields, intent-revealing names, enums for bounded values.

Knowledge points in this lesson

Prefer flat schemas over deep nesting
Name fields for intent, not implementation
Use enums when values are bounded
Descriptions should cover edge cases
Avoid union shapes that confuse the model
Required vs optional should reflect real use

Quick check

Tool Design & MCPSelect one

Which tool schema is most likely to produce reliable Claude tool calls?