D2 · Tool Design & MCP › Cluster 2 · Designing Great Tools

2.2 · Input Schema Design (JSON Schema, Enums)

Constrain the inputs

CONCEPT input_schema is a JSON Schema contract

The input_schema is a JSON Schema object describing the arguments Claude may send. It is the second half of the tool contract (the description being the first, 2.1): the description tells Claude whether to call the tool; the schema tells it how to shape the arguments. A well-built schema turns "Claude might guess" into "Claude can only produce valid inputs."

Schema toolWhat it doesDesign intent
typestring, integer, number, boolean, array, objectRejects wrong-typed values
properties[…].descriptionPer-parameter meaning & formatClaude fills the field correctly
enumFixed set of allowed valuesEliminates free-text drift
requiredWhich fields must be presentForces Claude to ask or supply them
strict: trueHard schema conformance (top-level field)Guarantees inputs validate exactly
🔑 Describe every property. A bare {"type": "string"} is as uninformative to Claude as a one-line tool description. Each property's description is where you say what the value means and what format it takes (e.g. "City and state, e.g. San Francisco, CA").

CONCEPT Enums, required, and defaults

Three levers do most of the work:

Marking a field required when it isn't forces Claude to fabricate a value. Mark it optional and describe the fallback instead — under-constraining a truly-required field is the mirror error.

DIAGRAM Schema narrows the space of inputs

flowchart TD A["Claude wants to call the tool"] --> B{"Schema constraints?"} B -->|"typed + enum + required
+ per-prop descriptions"| OK["🟢 Only valid inputs
possible"] B -->|"bare {type:string}
no enum, no required"| DRIFT["🟠 Free-text drift,
guessed values"] OK --> S{"strict: true?"} S -->|"yes"| HARD["🟢 Guaranteed to
validate exactly"] S -->|"no"| SOFT["🔵 Usually valid,
validate on your side"] classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef gate fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; classDef info fill:#cfe2ff,stroke:#0d6efd,color:#084298; class OK ok; class HARD ok; class DRIFT gate; class SOFT info;

CODE A well-constrained input_schema

Note the closed-set enum, the single required field, per-property descriptions, and the optional field whose default is documented in prose rather than relied on via the schema.

{
  "name": "get_weather",
  "description": "Get the current weather in a given location. Returns "
    "conditions and temperature. Use when the user asks about present "
    "weather; not for forecasts.",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "The city and state, e.g. San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],   // closed set → no drift
        "description": "Temperature unit. If omitted, defaults to celsius."
      }
    },
    "required": ["location"]        // only what's truly mandatory
  }
}
For complex, nested, or format-sensitive inputs, add an input_examples array of schema-valid sample objects — cheaper and clearer than prose for showing when to include optional fields. Pair with strict: true when you need a hard guarantee that tool_use.input validates.

TRADE-OFFS Tightly constrained vs. loosely typed schema

✅ Constrained schema (enum + required + descriptions)

  • Claude can only produce valid inputs
  • No value drift ("F" vs "fahrenheit")
  • Missing required → Claude asks instead of guessing

⚠️ Loose schema (bare strings, nothing required)

  • Fewer characters to write
  • But: free-text values, guessed arguments, silent malformation
  • You end up validating and re-prompting on the server

EXAM TRAPS

Trap: Using free-text where an enum fits. → A closed value set belongs in an enum, not a string with the options buried in the description. Enums stop value drift at the source.
Trap: Marking optional fields as required. → Claude will fabricate a value to satisfy the schema. Mark only truly mandatory fields; describe defaults in prose for the rest.
Trap: Relying on JSON Schema default to be applied. → The model does not reliably honor default. State the default behavior in the property's description instead.
Trap: Omitting per-property descriptions. → {"type":"string"} alone leaves Claude guessing meaning and format. Describe every property, just as you'd detail the tool itself.

PRACTICE

Q1 · A parameter accepts exactly "celsius" or "fahrenheit". How should you model it?

As an enum: "enum": ["celsius", "fahrenheit"]. A closed value set belongs in an enum so Claude selects from the list instead of producing free-text variants.

Q2 · Where do defaults belong, and why not the JSON Schema default keyword?

In the property's description ("If omitted, defaults to celsius"), with the field left optional. The model doesn't reliably apply the schema default keyword, so prose is the robust way to communicate fallback behavior.

Q3 · What does required buy you, and what's the failure mode of over-using it?

It forces Claude to supply (or ask for) those fields — Opus tends to ask when a required parameter is missing rather than guess. Over-marking fields as required makes Claude fabricate values to satisfy the schema, so list only the genuinely mandatory ones.