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 tool | What it does | Design intent |
|---|---|---|
type | string, integer, number, boolean, array, object | Rejects wrong-typed values |
properties[…].description | Per-parameter meaning & format | Claude fills the field correctly |
enum | Fixed set of allowed values | Eliminates free-text drift |
required | Which fields must be present | Forces Claude to ask or supply them |
strict: true | Hard schema conformance (top-level field) | Guarantees inputs validate exactly |
{"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:
enum— constrain to a fixed set. If a parameter has a small closed set of valid values (units, statuses, categories), list them as anenum. Claude then picks from the list instead of inventing"Fahrenheit"vs"fahrenheit"vs"F".required— mark only the truly mandatory. List genuinely required fields; Claude Opus tends to ask for a missing required parameter rather than guess. Everything else is optional.- Defaults — state them in the description. JSON Schema's
defaultkeyword is not reliably applied by the model, so the robust pattern is to make the field optional and describe the default behavior in itsdescription("If omitted, returns Celsius").
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
+ 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
}
}
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
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.required. → Claude will fabricate a value
to satisfy the schema. Mark only truly mandatory fields; describe defaults in prose for the rest.default to be applied. → The model does not
reliably honor default. State the default behavior in the property's description instead.{"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.