The mechanism
A tool schema is an executable interface contract. It tells clients what arguments exist and gives validators a way to reject malformed input. It does not decide whether a caller may access a particular incident. Treat schema validation and authorization as successive gates.
Prefer a business identifier to a free-form path or query. ParcelOps accepts incident_id, not a shell expression, SQL fragment or arbitrary URL. That narrows both the implementation and the explanation a reviewer must understand. Keep names and descriptions precise enough for selection without advertising capabilities the implementation lacks.
The current specification uses JSON Schema semantics, with the 2020-12 dialect as its default. Confirm which keywords your SDK and downstream model adapter actually preserve. A schema that appears in documentation but is dropped during model conversion cannot be your only enforcement layer.
Worked example
This is a tool definition fragment, not a complete tools/list response. additionalProperties: false rejects accidental extra fields. The pattern limits syntax; it is not an access-control rule. Keep an identical business check in the handler because callers can bypass model-side constraints.
{"name":"lookup_incident","description":"Read one authorized incident by exact ID.",
"inputSchema":{"type":"object","properties":{
"incident_id":{"type":"string","pattern":"^INC-[0-9]+$","maxLength":24}},
"required":["incident_id"],"additionalProperties":false}}Practice: predict, inspect, explain
Offline exercise. Write five candidate inputs: a valid ID, a missing property, an extra property, a shell-looking string and a syntactically valid ID belonging to another user. Predict schema outcomes first, then authorization outcomes. Do not send the foreign-object case to a real service.
Expected observation: the foreign-object example can pass the schema and must still fail access control. Add length and result-size limits to the design so a valid request cannot demand unbounded work. Explain how your error message helps correction without revealing whether an inaccessible record exists.
Troubleshooting and trade-offs
When models repeatedly choose the wrong tool, improve the semantic distinction between tools before widening inputs. When clients disagree about schema support, capture the exact exposed definition and adapter version. Do not silently coerce unknown fields into authority-bearing values. A default tenant ID or path can turn an omitted argument into surprising access.
Interview practice
Can a regex enforce authorization?
No. It limits syntax. Authorization depends on the authenticated principal, requested object and operation, using trusted application state.
Why avoid a universal query tool?
It expands authority, increases validation complexity and makes user review less concrete. Narrow operations expose intent more clearly and are easier to test.
Completion check
Produce a validation table that includes one schema-valid but unauthorized request.
Sources and version notes
This edition targets MCP 2026-07-28, checked 6 October 2026. SDK examples are version-sensitive and labelled when not executed. Synthetic fixtures are learning material, not protocol conformance evidence.
- Official documentation: Tools
- Official documentation: Index
- Official documentation: Client best practices
Make the understanding yours.
Use the completion check above. Mark this chapter when you can explain the mechanism and its limits.
Self-assessed reading progress. This does not certify that a lab ran or a system is secure.