All chapters
  1. Start hereThe model proposes a call. Your code decides whether it runs
  2. Foundations · 1Functions: arguments, return values and side effects
  3. Foundations · 2Tool calling: how a model asks, and the loop that answers
  4. Foundations · 3Tool schemas: names, descriptions and argument constraints
  5. Foundations · 4Types and annotations: one source for the schema and the handler
  6. Foundations · 5Result contracts: success, error, partial result, reference
  7. Protocols · 6Discovery and selection: how the right tool gets chosen
  8. Protocols · 7MCP architecture: host, client, server, tools, resources, prompts
  9. Protocols · 8MCP on the wire: transports, lifecycle, authorization, notifications
  10. Protocols · 9Retrieval: a tool the model calls, or knowledge it is given
  11. Production · 10Implementing tools: API wrappers, database queries, files, code execution
  12. Production · 11Safety: least privilege, validation, idempotency, sandboxing
  13. Production · 12Reliability: timeouts, retries, rate limits, circuit breakers
  14. Production · 13Testing tools: contracts, stand-ins, faults and traces
  15. Reference · 14Frameworks and standards: what each one does for a tool
  16. Reference · 15Advanced: composition, pagination, streaming, binary content, observability
  17. Reference · 16The insurance lab: one submission, five tools, end to end
  18. ReferenceGlossary
  19. AboutAbout this site and its sources
Foundations · 3

Tool schemas: names, descriptions and argument constraints

A tool definition is the only thing the model knows about your function. JSON Schema for the arguments, a name and a description that steer the choice, and constraints that reject a bad call before it runs.

What you will understand
Why the tool definition is everything the model knows about a function, and what each part of it steers.
What you can do
Write a JSON Schema for a tool's arguments, from one property to a nested write, with names and descriptions that guide the choice.
What you can prove
Which constraints a provider may enforce while the model writes, and which your validator must check on every call anyway.

In this site's own case UW-T01, the underwriting agent needs the roof age of submission SUB-1004. The model writes a request for get_roof_assessment, and the arguments look almost right:

{"submission_id": 1004}

The number is there. The prefix SUB- and the quotes are not. A Python function that receives this does not complain: Python does not check type hints when a function runs, so the integer would travel into the code that asks the roof-data provider, and that code would look for a record that cannot exist. In the example, nothing of the sort happens. The application checks the arguments against a description of what a valid call looks like, before anything runs, and sends this back:

{"ok": false, "error": {"code": "invalid_arguments", "message": "The arguments do not match the input schema of get_roof_assessment. /submission_id: expected string, got integer.", "retryable": false, "violations": [{"path": "/submission_id", "keyword": "type", "message": "expected string, got integer"}]}, "meta": {"tool": "get_roof_assessment", "attempt_number": 0, "duration_ms": 0, "evidence_ids": []}}

The model reads the path /submission_id, writes "SUB-1004" in its next turn, and the run goes on. That recovery depends on one artifact the model and the application share: the tool definition. The model used it to decide what to send. The application used it to decide that this was wrong. This page is about that artifact: what goes into it, how much the model learns from it, and why a description of valid input is never the same as a guarantee of valid input.

The first primitive of this site still holds here. The model proposes a call. Your code decides whether it runs.

The model knows only what the definition says#

The model never sees functions.py. It does not know that get_roof_assessment reads a provider stand-in, that the provider can time out, or that a submission id has four digits. Everything it knows about the function arrives with the request, in a small JSON object that the application sends along with the conversation. That object is the tool definition: a name, a description in plain words, and a description of the arguments.

A tiny example, shortened from the example's tools.py:

{"name": "get_roof_assessment",
 "description": "Look up the roof age that the roof-data provider assessed for one submission. Reads only; changes nothing.",
 "input_schema": {"type": "object", "properties": {"submission_id": {"type": "string", "pattern": "^SUB-[0-9]{4}$"}}, "required": ["submission_id"], "additionalProperties": false}}

Three parts, three jobs. The name is what the model writes when it asks for the tool. The description is how the model decides whether this tool fits the task at all. The third part, the input schema, is how the model decides what to put in the arguments, and it is also what the application checks the arguments against. One object serves two readers: a model that reads it as guidance, and code that reads it as a rule.

Before AI. A backend engineer has seen this split before. An HTTP API publishes an OpenAPI document; a client team reads it and builds requests from it; the server still validates every request body, because a published contract does not stop a client from sending something else. A Spring controller with a @Valid request body is the server half. The tool definition is the published contract, and the model is a client that read it once, a moment ago, and may still get it wrong.

Diagram: One tool definition, read four ways

Read left to right. The model reads the name and description to choose a tool, and the schema to fill in the arguments. A provider may enforce part of the schema while the model writes. Only the last column decides whether the call runs: the application's validator, on every call.

  1. 1 · Model chooses
    1. Name: What the model writes when it asks for the tool; must follow the provider's character rules.
    2. Description: The only place that says what the tool is for and when not to use it.
  2. 2 · Model fills in
    1. Input schema: Types, required fields, enums, patterns and ranges for each argument.
  3. 3 · Provider may enforce
    1. Strict mode: Constrains generation to schema-valid output, for the keywords the provider supports, when switched on.
  4. 4 · Application decides
    1. Validator: Checks the whole schema in code and returns each violation with its path.

The diagram shows who reads which part. The name and the description help the model choose. The input schema helps the model fill in the arguments. Some providers can also use the schema to constrain what the model writes; that box is drawn apart because it depends on the provider and covers only part of the schema. The last column is the only one that decides anything: the application's validator, which runs on every call whatever happened before.

JSON Schema, one property at a time#

The input schema is written in JSON Schema, a standard vocabulary for saying which JSON values are valid. The current release is 2020-12, as the specification page read on 2026-11-17 states. In plain words, a schema is a description of what a valid value looks like: "a submission id is text that starts with SUB- and has four digits".

Start with one value, the submission id, and add one rule at a time. The smallest schema says only the type:

{"type": "string"}

Under this schema "SUB-1004" is valid and 1004 is not, because 1004 is a number. That alone would have caught UW-T01. But "hello" is also a string, so the schema needs a second keyword, pattern, a regular expression the text must match:

{"type": "string", "pattern": "^SUB-[0-9]{4}$", "description": "The id of the submission, for example SUB-1004."}

The ^ and $ matter. JSON Schema's documentation, read on 2026-11-17, says a pattern matches anywhere in the string unless it is anchored, so without them "xxSUB-1004xx" would pass. The description inside the property is read by the model and ignored by the validator; it is the place for the example value.

Arguments arrive as an object, so the schema of a whole tool wraps the property in three more keywords. properties names the fields and gives each its schema. required lists the fields that must be present; JSON Schema treats every property as optional unless it is listed here. additionalProperties: false forbids any field that is not named, which JSON Schema otherwise allows by default. Here is the complete input schema of get_roof_assessment, as tools.py defines it:

{"type": "object",
 "properties": {"submission_id": {"type": "string", "pattern": "^SUB-[0-9]{4}$", "description": "The id of the submission, for example SUB-1004."}},
 "required": ["submission_id"],
 "additionalProperties": false}

Each line removes one way to be wrong. Without required, the model could send {}. Without additionalProperties: false, it could send {"submission_id": "SUB-1004", "detail": "full"}, and the extra field would be silently passed on or silently dropped, depending on the code behind it. Neither is acceptable for a tool whose arguments come from a model that read untrusted text.

The keywords used in the example, now that each has appeared in context:

KeywordWhat it saysWhere the example uses it
typeThe JSON type, or a list of typesevery field; ["integer", "null"] for an unknown roof age
propertiesThe named fields of an object and their schemasevery tool's arguments
requiredFields that must be presentsubmission_id; the seven required fields of a recommendation
additionalProperties: falseNo other fields allowedevery object in the example
enumOne of a fixed list of valuesthe recommendation; occupancy; wind zone
constExactly this one valuerequires_human must be true
patternText must match a regular expressionsubmission id, rule ids, idempotency key
minLength, maxLengthLength of textquery of search_guidance: 3 to 200 characters
minimum, maximumRange of a number, both ends includedtop_k 1 to 5; stated_confidence 0 to 1
items, minItems, maxItemsThe schema of each element, and how manyreasons: 1 to 8 strings

An enum deserves a sentence of its own. It lists every allowed value, so the model cannot invent a new one: the recommendation is one of approve, decline, request_info and escalate, and bind_policy is not on the list. OpenAI's function-calling guide, read on 2026-11-17, recommends enums and object structures for the same reason: so that invalid states cannot be expressed.

The whole schema of the write#

The write tool, record_recommendation, is where the schema carries the most weight, because what it stores is what the underwriter will read. The model recommends; a person decides. Here is its input schema from tools.py, with the constants SUBMISSION_ID, RECOMMENDATION_SCHEMA and IDEMPOTENCY_KEY written out in place and descriptions shortened:

{"type": "object",
 "properties": {
   "submission_id": {"type": "string", "pattern": "^SUB-[0-9]{4}$"},
   "recommendation": {
     "type": "object",
     "properties": {
       "recommendation": {"type": "string", "enum": ["approve", "decline", "request_info", "escalate"], "description": "What the agent recommends. A person decides."},
       "reasons": {"type": "array", "items": {"type": "string", "minLength": 1, "maxLength": 400}, "minItems": 1, "maxItems": 8},
       "citations": {"type": "array", "items": {"type": "string", "pattern": "^R-[A-Z]+-[0-9]{2}$"}, "maxItems": 10},
       "missing": {"type": "array", "items": {"type": "string"}, "maxItems": 10},
       "stated_confidence": {"type": "number", "minimum": 0, "maximum": 1},
       "requires_human": {"type": "boolean", "const": true},
       "policy_version": {"type": "string", "pattern": "^[0-9]{4}\\.[0-9]+$"},
       "evidence_ids": {"type": "array", "items": {"type": "string", "pattern": "^EV-[A-Z]+-[0-9][0-9-]*$"}, "maxItems": 10}
     },
     "required": ["recommendation", "reasons", "citations", "missing", "stated_confidence", "requires_human", "policy_version"],
     "additionalProperties": false
   },
   "idempotency_key": {"type": "string", "pattern": "^SUB-[0-9]{4}:run-[0-9a-f]{4}:recommendation$"}
 },
 "required": ["submission_id", "recommendation", "idempotency_key"],
 "additionalProperties": false}

Read it as a list of decisions about the business, written in a language a validator can check. A recommendation must give at least one reason, so an empty justification cannot reach the cockpit. Citations must look like rule ids of the policy fixture, such as R-ROOF-03 in case UW-004, so a free-text "roof rule" is refused. requires_human is fixed to true with const: no call can store a recommendation that claims to need no person. And the idempotency key has the exact shape the application builds, SUB-1004:run-7f3a:recommendation in UW-004, so a key the model made up, such as retry-2, is refused before it can break the guarantee that a retry stays one row.

Note what the schema cannot say. It cannot check that R-ROOF-03 exists in version 2026.2 of the policy fixture, that SUB-1004 is a real submission, or that the citations support the recommendation. A schema describes the shape of one value. Facts about the world, and rules that relate two fields, belong to code that runs after validation.

Common confusion. A required field is a field that must be present, not a field that must be non-empty or non-null. JSON Schema's documentation is explicit that a null value does not count as absent. The example's roof age is required on a submission and may still be null ("type": ["integer", "null"]), which is how UW-003 says "unknown" without leaving the field out.

Names and descriptions steer the choice#

A schema tells the model how to fill in a call. Whether the model calls this tool at all depends mostly on the name and the description. The description is the tool's only chance to say what it is for, when to use it and when not to, and what comes back.

Compare two descriptions from tools.py. The read:

Look up the roof age that the roof-data provider assessed for one submission. Use it to check the roof age
stated on the application. Reads only; changes nothing. Returns roof_age_years, an evidence_id and a
reference to the full report. If the provider has no record, the result is an error with code not_found.

The write:

Store the agent's recommendation for the underwriter, who decides. WRITES one row with status
awaiting_underwriter. Call it once, at the end, with the idempotency_key given in the request.
It cannot approve, decline, bind or quote anything.

Each sentence carries a decision. "Use it to check the roof age stated on the application" tells the model when the tool fits. "Reads only; changes nothing" and "WRITES one row" separate the harmless call from the one that leaves a trace. "If the provider has no record, the result is an error with code not_found" prepares the model for case UW-003 before it happens. "It cannot approve, decline, bind or quote anything" answers the question a model might otherwise guess at. That is a tool description doing its job: telling a reader with no other source what the function does, when to use it, and what it returns.

The vendors' documentation, read on 2026-11-17, says the same in its own words. Anthropic's "Define tools" page calls detailed descriptions the most important factor in tool performance and suggests at least three to four sentences per tool, covering what it does, when to use it and when not, what each parameter means, and its caveats. Gemini's page asks for clear, specific descriptions and descriptive names without spaces or special characters. Anthropic's article on writing tools for agents advises unambiguous parameter names, such as user_id rather than user. The example follows that advice: submission_id, never id.

Names have rules of their own. As documented on 2026-11-17, Anthropic requires a tool name to match ^[a-zA-Z0-9_-]{1,128}$, and the MCP specification, revision 2026-07-28, says a name SHOULD use only ASCII letters, digits, underscore, hyphen and dot. A name with a dot is therefore fine in MCP and refused by one provider API. Pick the narrower set if a tool may travel.

Production pitfall. A description is guidance, not a control. "Call it once, at the end" does not stop a model from calling record_recommendation twice; the idempotency key in the adapter does. "It cannot approve anything" is true because no such tool exists in the registry, not because the sentence says so. Write descriptions to help the model choose well, and put every rule that must hold into code. How to word instructions and descriptions as prompts, in depth, belongs to Prompt Engineering.

What a provider may enforce while the model writes#

So far the schema has been a description that the model reads and the application checks afterwards. Several providers now offer more: they can use the schema while the model is writing, so that the output cannot leave the allowed shape. This is called constrained generation, and the switch that turns it on is usually called strict mode.

As documented on 2026-11-17, Anthropic's strict tool use is a top-level "strict": true in the tool definition, next to name, description and input_schema. The page says it constrains the model's token sampling to schema-valid outputs ("grammar-constrained sampling") and guarantees two things: the tool input follows the input_schema, and the tool name is always valid. OpenAI's function tools carry the same strict boolean. Its guide says strict mode requires additionalProperties: false on every object and every property listed in required, with optional fields written as a type that allows null, such as ["string", "null"]. In the Responses API, if strict is left out, the API tries to make the schema strict and falls back to non-strict if it cannot. Gemini's page describes a validated mode, with schema adherence ensured, and says only a subset of the OpenAPI schema is supported.

The words that matter are "a subset". Each provider enforces a documented part of JSON Schema, and the parts differ. Here are the keywords of the example against the two subsets read today:

Keyword in the exampleAnthropic strict (structured-outputs subset)OpenAI strict (supported schemas)
type, properties, required, enumsupportedsupported
additionalProperties: falserequired on every objectrequired on every object
constsupportednot named in the list read
patternsupported, without backreferences, lookaround or word boundariessupported
minimum, maximumnot supportedsupported
minLength, maxLengthnot supportednot named in the list read
minItems, maxItemsminItems of 0 or 1 onlysupported
optional fieldsallowed (required lists a subset)every field must be required; optional means "may be null"

Two conclusions follow from the table. First, the same schema is enforced differently by different providers: top_k between 1 and 5 is enforced while the model writes on one API and not on the other. Second, a schema that is legal JSON Schema may be rejected outright. Anthropic's page says an unsupported feature returns a 400 error, and its SDK helpers, as documented, remove unsupported constraints such as minimum from the schema they send, copy them into the field's description, and check the response against the original schema afterwards if the helper validates. In other words, the provider's own SDK falls back to validation in code for the constraints the model cannot be held to.

Anthropic's strict-mode page also says strict use means there is "no need to validate and retry tool calls". Read that claim narrowly. It is a guarantee about the shape the provider enforced, for the subset it supports, on a request where strict mode was on. It says nothing about constraints outside the subset, about a request sent without strict mode by another code path, about a different model or provider behind the same loop, or about rules no schema can express. The MCP specification, revision 2026-07-28, puts the obligation where it belongs: servers MUST validate all tool inputs.

What this is not. This page covers the input schema of a tool and how it is checked. Typed data contracts in general, parsing and repairing model output, and how a schema evolves without breaking its readers are the subject of Schema Engineering. How one typed source in code produces this schema is the next page, Types.

Validation you do anyway#

In the example, the check runs in the execution adapter, the code between the model's request and the function. Step 2 of Executor.execute_detailed in executor.py calls schema.validate(arguments, tool.input_schema) before authorization and before any attempt. The validator is a teaching subset of JSON Schema, about a hundred lines in schema.py; its docstring says a production system uses a full validator. It returns every violation as a path, a keyword and a message, and an empty list means valid. Its contract, quoted from schema.py:

def validate(instance: Any, schema: dict[str, Any], path: str = "") -> list[dict[str, str]]:
    """Every way `instance` breaks `schema`, as a list of {path, keyword, message}. Empty list: valid.

    Keywords are checked in a fixed order so the output is the same on every run:
    type first (if the type is wrong, the other keywords of that level are skipped),
    then const, enum, the string, number, object and array keywords.
    """

The script below was written for this page and run in a scratch copy of the example. It loads a tool's definition from the registry, validates each argument object given on the command line, and prints the violations. A successful run proves that the validator rejects UW-T01's number with a path the model can act on, accepts the corrected call, and reports several violations at once rather than stopping at the first. It does not prove anything about a model: the model here is a scripted stand-in, so these results show how the tool layer works, not how good any model is.

import json
import sys

from schema import validate
from tools import REGISTRY

tool = REGISTRY.resolve(sys.argv[1])
for text in sys.argv[2:]:
    arguments = json.loads(text)
    violations = validate(arguments, tool.input_schema)
    print(text)
    if not violations:
        print("  valid")
    for v in violations:
        print(f"  {v['path'] or '(arguments)'}  {v['keyword']}: {v['message']}")
cd examples/uw-tools
/opt/homebrew/bin/python3 check_args.py get_roof_assessment '{"submission_id": 1004}' '{"submission_id": "SUB-1004"}' '{}' '{"submission_id": "SUB-04", "detail": "full"}'
{"submission_id": 1004}
  /submission_id  type: expected string, got integer
{"submission_id": "SUB-1004"}
  valid
{}
  /submission_id  required: missing required field submission_id
{"submission_id": "SUB-04", "detail": "full"}
  /detail  additionalProperties: unknown field detail
  /submission_id  pattern: must match ^SUB-[0-9]{4}$; got "SUB-04"

The same script against the write, with three mistakes in one recommendation: a verdict that is not on the list, a citation that is not a rule id, and a recommendation that claims to need no person.

/opt/homebrew/bin/python3 check_args.py record_recommendation '{"submission_id": "SUB-1004", "recommendation": {"recommendation": "bind", "reasons": ["Roof is old."], "citations": ["roof"], "missing": [], "stated_confidence": 0.6, "requires_human": false, "policy_version": "2026.2"}, "idempotency_key": "SUB-1004:run-7f3a:recommendation"}'
{"submission_id": "SUB-1004", "recommendation": {"recommendation": "bind", "reasons": ["Roof is old."], "citations": ["roof"], "missing": [], "stated_confidence": 0.6, "requires_human": false, "policy_version": "2026.2"}, "idempotency_key": "SUB-1004:run-7f3a:recommendation"}
  /recommendation/recommendation  enum: must be one of "approve", "decline", "request_info", "escalate"; got "bind"
  /recommendation/citations/0  pattern: must match ^R-[A-Z]+-[0-9]{2}$; got "roof"
  /recommendation/requires_human  const: must be True

Each path is a JSON Pointer: /recommendation/citations/0 is the first citation inside the recommendation. That is what makes the error usable by a model, which has to find the exact field to change. (The True in the last line is Python's spelling of the JSON value true; the validator prints Python values in its messages.) In the loop, the adapter puts this list into the result under violations, as in the UW-T01 result at the top of this page, and the model corrects the call in its next turn.

The lab below runs the same validator in the browser. Pick a tool, edit the arguments as JSON, and see every violation with its path and keyword. The buttons load the example's test rows and show the Python result next to the browser's. The table after it lists a selection of those rows.

ToolArgumentsViolations (path, keyword)
get_roof_assessment{"submission_id": 1004}/submission_id type: expected string, got integer
get_roof_assessment{}/submission_id required
get_roof_assessment{"submission_id": "SUB-1004", "detail": "full"}/detail additionalProperties
get_roof_assessment{"submission_id": "SUB-04"}/submission_id pattern
search_guidance{"query": "ro", "top_k": 9}/query minLength; /top_k maximum
search_guidance{"query": "roof age", "top_k": 2.5}/top_k type: expected integer, got number (2.0 counts as an integer)
check_eligibilityoccupancy castle, area -5, sprinklered "yes", extra field colour/submission/colour additionalProperties; /submission/occupancy enum; /submission/area_sq_ft minimum; /submission/sprinklered type
record_recommendationrecommendation bind, requires_human false, citation roofenum, const and pattern, each with its path under /recommendation
record_recommendationidempotency key retry-2/idempotency_key pattern

Diagram: Case UW-T01: a wrong type caught before anything runs

Time runs down the page. The model's first call has a number where the schema wants text. The adapter validates before it executes, so the function never runs. The model reads the path, corrects the value, and the second call succeeds.

  1. Model (scripted stand-in) to Execution adapter: call_01 {submission_id: 1004}. A number where the schema requires a string matching ^SUB-[0-9]{4}$.
  2. Execution adapter: validate: 1 violation. Path /submission_id, keyword type, expected string, got integer.
  3. Execution adapter to Model (scripted stand-in): invalid_arguments, attempt 0. The result lists the violation with its path; retryable is false because the same call would fail again.
  4. Model (scripted stand-in) to Execution adapter: call_04 {submission_id: SUB-1004}. The corrected call, in the model's next turn.
  5. Execution adapter to Function: valid, authorized: run. Only now does the function run.
  6. Function to Execution adapter: roof age 22, EV-ROOF-0412. The provider stand-in's answer for SUB-1004.
  7. Execution adapter to Model (scripted stand-in): ok, attempt 1. The result envelope with the data; the run continues as in UW-004.

When the check is missing#

The example can switch validation off (AdapterOptions(validate=False)), which turns it into a demonstration of the mistake this page warns against. With the switch off, UW-T01's {"submission_id": 1004} reaches the function. The test test_without_validation_the_bad_value_reaches_the_provider in test_tools.py records what happens next: the roof-data provider stand-in is called once, finds no submission 1004, and the result is not_found.

That result is worse than an error. It is a wrong fact delivered as a correct one. The model reads "the provider has no record", treats the roof age as unknown, and may recommend request_info under R-ROOF-02 for a submission whose roof the provider assessed at 22 years. Nothing crashed, the provider answered politely, and the underwriter receives a recommendation built on a typo. A validator turns that silent wrong answer into a loud, specific one, invalid_arguments at /submission_id, at the one moment the model can still fix it.

The same idea in the protocols#

The provider APIs and MCP all carry the same three parts, under slightly different field names. These shapes are the documented shape; not run here, written from each specification or guide as read on 2026-11-17.

WhereNameDescriptionArguments schemaStrict switch
Anthropic Messages APInamedescriptioninput_schemastrict (top level of the tool)
OpenAI Responses APInamedescriptionparametersstrict
Gemini API (generateContent)namedescriptionparameters or parametersJsonSchemamode VALIDATED in the function-calling config
MCP tools/listname (plus optional title)descriptioninputSchemanone: MCP describes tools, it does not generate calls

MCP adds a few rules of its own. As the 2026-07-28 tools page states, inputSchema must be a valid JSON Schema object, not null; a schema without $schema defaults to 2020-12; and for a tool with no parameters it recommends {"type": "object", "additionalProperties": false}, which accepts only an empty object. Because an MCP server can be reached by clients bound to different model APIs, a schema written for MCP should stay inside the narrowest subset those APIs enforce, or accept that some constraints will be checked only by the server. Frameworks keeps JSON Schema itself apart from these vendor details, and MCP architecture explains where tools/list sits.

In a coding agent. A coding agent's run_tests tool might take {"suite": {"type": "string", "enum": ["unit", "integration"]}}, so the model cannot ask for a suite that does not exist. Its edit_file tool takes a path with a pattern that refuses ... But no pattern can say "inside this repository after symbolic links are followed": that check belongs in the harness code that executes the edit. A schema narrows what the model can ask for; it does not replace the boundary check on what the code then touches. Harness Engineering covers that runtime.
Regular expressions in schemas: one pattern, several enginesThe same pattern can mean different things in the provider, the browser and your validator

JSON Schema's documentation, read on 2026-11-17, says pattern uses ECMA-262 regular expressions, the dialect of JavaScript. Your validator may not. The example's validator is written in Python and checks a pattern with re.search. In Python, $ also matches immediately before a newline at the end of the text. The run below, in the same scratch copy, shows the consequence:

/opt/homebrew/bin/python3 check_args.py get_roof_assessment '{"submission_id": "SUB-1004\n"}'
{"submission_id": "SUB-1004\n"}
  valid

"SUB-1004\n" passes the example's validator, where a JavaScript engine without the multiline flag would refuse it. The function then runs with an id that matches no submission. Here the damage is a not_found; in a tool that builds a file path or a query from the value, the extra character could matter more. The fix in Python is re.fullmatch or an anchor of \Z, and the lesson is wider: test each pattern in every engine that enforces it. A provider's constrained generation, a browser lab, a Python validator and a Java Pattern.matcher(...).matches() are four engines. (The example's Java handler uses matches(), which requires the whole string.)

Dialects differ in other places too. Anthropic's structured-outputs page, as documented on 2026-11-17, lists backreferences, lookahead and lookbehind, and word boundaries as unsupported. Unicode digit classes differ between engines: the example avoids \d and writes [0-9], which means the same thing everywhere. Keep patterns to anchored literals, character classes and simple counts, and let code check anything subtler.

Validate first or authorize first?A detailed validation error describes the schema; decide who may learn it

The example validates before it authorizes. Its executor.py docstring says so, and notes the alternative: an adapter that must not reveal a schema to an unauthorized caller checks scopes first. The difference is small for this example and real elsewhere.

A validation error is information. UW-T03 is the case where the assessment-agent, which holds only the scope uw.read, asks for record_recommendation. With validation first, a malformed request from that caller gets back the exact shape of a valid recommendation, path by path, before it learns it may not write at all. The definitions are not secret here, and the caller's catalog would not even offer the write tool. But in a system where the existence or shape of a tool is sensitive, such as an administrative operation or a tool that reveals which fields an internal record has, authorization should run first, and an unauthorized caller should get not_authorized without detail.

There is a cost in the other direction. Authorizing first means looking up permissions for requests that would fail anyway, and the authorization code must cope with arguments that are not yet known to be well-formed. If authorization depends on an argument, such as the submission's owner, it must parse that argument defensively. A common design keeps two steps: a cheap structural check that the arguments are an object, then authorization of the tool, then full validation, then authorization of the specific resource.

Strict schemas and changeadditionalProperties false protects today and breaks tomorrow's callers; plan the version

additionalProperties: false is the right default for a tool's input: it stops a model from smuggling fields, and both strict modes read for this page require it. It also makes every schema change visible. Add an optional field inspection_date to get_roof_assessment, and every caller that does not know it keeps working. Remove a field, rename one, or tighten a pattern from ^SUB-[0-9]{4}$ to five digits, and every stored call, every test fixture, and every prompt that shows an example call becomes invalid at once.

With a model as the caller, the definitions are sent on every request, so the model sees the new schema immediately. Other callers do not: recorded traces replayed in tests, another agent built against last month's catalog, an MCP client that cached tools/list. Treat a breaking change to an input schema the way you treat one to a public API: a new tool name or a version in the name, a period in which both are offered, and a test that replays old recorded calls against the new schema. Advanced covers versioning a tool, and schema evolution in depth belongs to Schema Engineering.

OpenAI's strict mode adds one twist, as documented on 2026-11-17: every field must be listed in required, and optional means "may be null". A tool designed with optional fields must be rewritten for it, and code must then treat null as "not given". That is a different contract from a missing field, and the function behind the tool has to know which one it is getting.

What a large schema costsDefinitions are input on every turn, and constrained generation has limits

A tool definition is not free. OpenAI's guide, read on 2026-11-17, says function definitions are injected into the system message, count against the context window and are billed as input tokens. Anthropic's overview says the same in its own terms: the tools parameter adds input tokens, as does a tool-use system prompt the API builds. The definitions go with every turn of the loop, so the five definitions of the example are paid for four times in UW-004.

That cost pushes in the wrong direction. A team trims descriptions to save tokens and removes exactly the sentences that tell the model when not to use a tool. Trim the schema instead: shorter property descriptions where the name is clear, no defaults that the model never needs to know, and no deeply nested objects where two flat fields would do.

Constrained generation has its own limits. Gemini's page, as documented on 2026-11-17, says very large or deeply nested schemas may be rejected and that exceeding constrained-decoding limits gives 400 INVALID_ARGUMENT; its suggested fixes are to split tool sets, flatten schemas, and reduce optional fields and unions. OpenAI's structured-outputs page states numeric limits, such as up to 5,000 object properties in total and up to 10 levels of nesting. A schema that works on one provider can fail on another for size alone, which is one more reason to keep the validator in your own code as the reference.

Checklist for Monday#

CheckWhy
Every tool definition has a name, a description of three or more sentences, and an input schemaThe definition is all the model knows
The description says when to use the tool, when not, whether it reads or writes, and what an error looks likeIt steers the choice; UW-003's not_found is announced in advance
Every object sets additionalProperties: false and lists its required fieldsNo smuggled fields, no silent omissions
Identifiers have anchored patterns that use [0-9], tested in every engine that enforces them"SUB-1004\n" passes a Python re.search with $
Closed sets are enums; fixed values are constThe model cannot invent a verdict or drop requires_human
Arguments are validated in code on every call, before execution, with paths in the errorStrict modes enforce different subsets, and only when switched on
Rules between fields and facts about the world are checked after validation, in codeA schema describes one value's shape
Schema changes are versioned like public API changesOld calls, fixtures and cached catalogs break otherwise

In one breath#

A tool definition is a name, a description and a JSON Schema for the arguments, and it is everything the model knows about your function. The name and description decide whether the model picks the tool; the schema decides what it writes, and some providers can enforce part of that schema while the model writes. Every provider enforces a different subset, so the application validates every call in code, before it runs, and sends back a precise error the model can fix.

You can now write the definition of a tool, from one property to a nested write, and check calls against it. What you have written twice is the truth about each argument: once in the function's type hints and once in the schema, and nothing keeps the two in step. If a developer changes the page size in functions.py, the schema in tools.py still says 5. Types makes one typed source produce both.