When should a tool parameter be required versus optional in its JSON Schema?

## What `required` actually does In JSON Schema, `required` is an array of property names on the object that must be present. In a tool definition it does double duty. Mechanically it is a validation rule, and under strict decoding modes it is enforced. Behaviourally — and this is the part interviews are testing — it is an instruction to the model about what it must have in hand before it is allowed to call. That behavioural half is the useful one. When a field is required and the conversation has not supplied it, a well-prompted model asks the user. When the same field is optional, the model has permission to proceed without it, and will. Requiredness is therefore one of your few levers for making an agent gather information rather than assume it. ## The optionality trap Every optional field is a small invitation to hallucinate. Consider an insurance first-notice-of-loss tool with an `adjuster_notes` string marked optional. Nothing in the schema says the notes must originate from the caller. A helpful model, having been told the field exists, will often fill it with a fluent summary that reads like it came from the conversation but contains details nobody stated. The output validates perfectly. It is still wrong, and because it validates, no runtime check catches it. Three defences, in order of effectiveness: 1. **Delete the field.** If your handler can compute or default it, it does not belong in the model's schema at all. Most fields that end up optional are actually handler concerns that leaked into the interface. 2. **Describe the omission condition.** If the field must stay, its description should say when to leave it out and where legitimate values come from: "optional free-text notes stated by the caller; omit entirely if the caller did not volunteer them; never summarise or infer". 3. **Constrain the value space.** Where the field is categorical, an `enum` replaces open text with a closed set and removes the fabrication surface. ## Enums and the value axis `required` governs presence; `enum` governs value. A claims tool with `claim_type` as a free string will receive `"auto accident"`, `"car crash"`, `"collision"` and `"AUTO_COLLISION"` from the same model on different days, and your handler has to normalise all of them. The same field declared as an enum of six values — `auto_collision`, `auto_theft`, `property_fire`, `property_water`, `property_theft`, `liability` — makes the mapping the model's job at generation time, which is exactly where it belongs, and under strict decoding makes an out-of-set value impossible rather than merely unlikely. Enums also teach. Seeing the six categories tells the model what the domain looks like, which improves the choice, not just its formatting. The limit is cardinality: a fifty-value enum is a taxonomy the model must scan on every turn, and at that size a lookup tool or a two-step flow usually reads better than a wall of literals. ## Nested objects Nesting is how you express structure that genuinely belongs together — an `incident` object holding `occurred_at` and a `location` object with `city`, `region` and `country`. Nested objects carry their own `required` arrays, so you can say that a location must have a city and a country while region is optional. Use nesting when the grouping is real and reused, not to mirror your internal domain model. Deep nesting hurts twice: it costs tokens on every turn, and each additional level is another place for the model to produce a structurally valid but semantically empty object — an `incident` present, correctly shaped, and containing invented values. Two levels is comfortable; beyond three, flatten or split the tool. ## A worked shape For the claims tool: `policy_number` required, because filing without one is meaningless and the value can only come from the caller. `claim_type` required and enumerated, because routing depends on it and the model can classify from the narrative. `incident` required, with `occurred_at` and `location` required inside it. `adjuster_notes` optional, with a description that says to omit it unless the caller volunteered the text. Nothing else — timestamps, channel, agent id, correlation ids all belong to the handler and never appear in the schema. ## What stays on the server A final discipline: `required` is guidance to the model, and under strict modes a shape guarantee, but never a trust boundary. The handler validates regardless — presence, ranges, referential existence, authorisation. A schema makes the right call likely and the wrong shape impossible; it does not make the value true. `policy_number` may be perfectly formatted, present, and belong to a different customer.