Tool Schema Security
Does the tool’s declared interface match what its server will actually accept?
Reference notes by Min · Reviewed October 15, 2026
Definition
Tool schema security is the design and enforcement of the structured contract through which an agent requests an operation. It covers allowed fields, types, limits and semantics, while leaving resource authorization to the service that performs the action.
The schema is part of the agent’s understanding of a tool, but the server determines what really happens. A mismatch can create both ordinary errors and security gaps. Review the published contract and execution behavior together when a connector changes.
What it covers
- Shape
- Required and permitted fields.
- Bounds
- Lengths, values and collection sizes.
- Semantics
- Meaning of identifiers, units and operation choices.
- Version
- Agreement between published schema and server behavior.
Separate structural and semantic checks. A string can have valid syntax while identifying another tenant’s record. A numerical amount can be well-formed while using the wrong currency. The tool contract should make intent clear, and the service should enforce business meaning.
In practice
Practical design patterns by Min.
- Reject unsupported fields rather than silently accepting arbitrary input.
- Use explicit units and narrow operation choices.
- Validate at execution even when the model interface claims structured output.
Version schemas alongside tool implementation and evaluation cases. Include missing, extra and boundary-value fields in integration checks. Avoid revealing internal credentials or sensitive debugging details when validation fails; give the agent a clear reason it can safely act on.
Research notes
Source-grounded details and editorial applications. Follow each link for the original document.
Listed properties are not automatically required
JSON Schema distinguishes properties, required fields and additional-property behavior. Those details matter when designing a narrow tool interface, but they do not express every business permission.
Working example
A refund tool accepts an unexpected destination
The declared interface takes an order ID, but the backend also accepts a recipient field.
- Remove or explicitly govern the extra field.
- Test inputs against the actual server contract.
- Resolve the permitted recipient from trusted order state.
Why the controls matter
The refund example exposes a field the agent should not control. Even if normal clients omit it, an attacker or faulty caller may supply it. Restricting the destination through trusted state is stronger than hoping generated arguments follow the visible schema.
Common pitfalls
- Assuming properties are required simply because they are listed.
- Trusting client-side schema validation.
- Using a free-form command field for every operation.
Strict validation can break legitimate older clients, so plan compatibility changes deliberately. Do not relax the entire contract to fix one migration problem. Record which versions remain supported and when obsolete interfaces are retired.
Questions for operational review
Use these questions to decide what evidence your team needs. They are editorial prompts, not a compliance checklist.
- Does the backend accept more than the declared schema?
- Where are business identifiers authorized?
- How are schema changes evaluated before deployment?
Articles linking here
References
Primary documents reviewed for this entry. Examples and implementation patterns are editorial synthesis.
- JSON Schema: Object validation reference ↗Accessed October 15, 2026
- OWASP: Authorization Cheat Sheet ↗Accessed October 15, 2026