A tool definition has two jobs, and only one of them is JSON. The schema says what shape the arguments take; the descriptions say what the tool is for and what each argument means. A schema can be perfectly valid and still produce a tool that gets called at the wrong moment with plausible-looking nonsense in it, because nothing in the JSON explains what any of it is. This builder writes the schema and checks both halves: the structure, and whether anything in it is actually described. Strict mode is handled properly too — it requires every property to be listed as required and disallows extra ones, which catches people out because the schema is otherwise unchanged.
Features
Parameters with types, descriptions and optional closed value sets
Strict mode's all-required rule enforced rather than discovered later
additionalProperties set correctly when strict mode is on
Arrays given an items schema automatically
Warns about an undescribed parameter
Catches duplicate parameter names
Notes an enum with a single value, which is a constant
Emits the whole tool definition, not just the schema
How to use the MCP Tool Schema Builder
Name the tool and describe when it should be used
Add each parameter with its type and a description
Mark which are required, or turn on strict mode
Copy the definition into your tools array
Example
Input
"strict": true
Output
Error: strict mode requires every property to be listed as required
Strict mode does not allow optional properties — allow null instead.
Common errors & troubleshooting
Strict mode is rejected. — It requires every property to be required and additionalProperties to be false. Mark the optional ones required and allow null, or turn strict mode off.
The tool is called with the wrong arguments. — Usually undescribed parameters. A name alone leaves the meaning to be inferred, and “id” could be anything.
The tool is called at the wrong time. — That is the tool description, not the schema. Say when to use it and what it returns, not just what it does.
An array parameter is rejected. — Arrays need an items schema saying what they contain. One is added here automatically.
Frequently asked questions
What does strict mode actually change?
It guarantees the arguments validate against the schema exactly. The cost is that every property must be listed as required and no extra properties are allowed, so genuinely optional arguments have to be modelled as required-but-nullable.
How detailed should a parameter description be?
Enough that someone reading only the schema would know what to put there — the format, the units, where the value comes from. “The customer email address the order was placed under” is worth far more than “email”.
When should I use an enum?
When the set of valid values is genuinely closed and short. It removes a whole class of wrong answers. A single-value enum is flagged because it is a constant rather than a parameter.
Does this work for MCP tools and API tools?
The schema is the same JSON Schema subset in both cases. The wrapper differs slightly between contexts, but the input schema — which is the part that is easy to get wrong — is identical.
What makes a good tool description?
Three things in a couple of sentences: what it does, when to reach for it, and what comes back. The last one is the most commonly omitted and the most useful, because it tells the caller whether one call will be enough.
Related tools
Tool Schema Checker — Paste a tool definition and find out why it is rejected or mis-called.
MCP Server Config Builder — Generate an MCP server entry for stdio, HTTP or SSE — and the CLI one-liner.