A schema can require a string without explaining which string is valid. Agents and developers both benefit when the input contract describes meaning, units and relationships.
Quick answer: Define each field's purpose, type, valid range or format, units and relationship to other fields. Include a realistic valid example and a meaningful invalid case. Put constraints in enforceable validation where possible, and keep descriptions consistent with actual server behavior.
Make ambiguous names concrete
For an illustrative route tool, a field named “location” leaves several questions open. Is it a city, a postal address, a coordinate pair or an internal identifier? Which coordinate order is expected?
A persuasive description should not compensate for a server that silently accepts incompatible forms.
Review the input contract
| Property | Example question |
|---|---|
| Meaning | What real-world value does this represent? |
| Format | Which syntax or identifier system is valid? |
| Units | Seconds, milliseconds or another unit? |
| Required relationship | Must another field be present? |
| Default | What happens when it is omitted? |
| Validation | How is an invalid value rejected? |
These questions are proposed design guidance; they do not describe an actual route API contract.
Keep examples honest
Use fictional coordinates or a clearly identified public fixture as appropriate. Label sample values. Do not present a successful-looking response as a measured result unless the example was actually run and its conditions are preserved.
A minimal example should include every required field. An optional field that changes cost or side effects deserves an explanation beside it.
Test interpretation
Ask a reviewer to map a plain-language task into arguments, then inspect the submitted values. Use a near miss such as swapped coordinate order or an ambiguous time zone.
I'm Shashank Agarwal, creator of API.market and founder and CEO of Noveum AI. See the MCP tools specification for the named June 2025 version for schema fields, and API.market setup for the gateway.
The tool-boundary guide explains why the actual submitted arguments matter during review.
Follow my work on LinkedIn. Drafted with AI assistance.
Top comments (0)