How to Write and Check a JSON Schema for an AI Agent Tool

Every tool an AI agent can call needs a description of what it accepts. In the Model Context Protocol (MCP), that description is a JSON Schema in a field called inputSchema. If the schema is vague, the model guesses. If it is wrong, valid calls get rejected. This guide shows a simple routine for writing a schema, testing it and keeping it stable, using free browser tools for each step.

The details below come from the current draft of the MCP tools specification. It is a draft, so check the specification page before you ship, because wording and requirements can change.

What the specification says a tool definition contains

According to the draft, a tool has a unique name, an optional human-readable title, a description, and an inputSchema that is a JSON Schema object. It may also have an outputSchema for structured results. Three details are worth knowing before you start:

• If you do not set a $schema field, the schema is treated as JSON Schema 2020-12.
• The input schema must be a valid schema object, never null.
• Tool names should be 1 to 128 characters, case-sensitive, and limited to letters, digits, underscore, hyphen and dot.

Step 1: Write the smallest schema that is true

Start with the tool's real inputs, not the inputs you wish it had. A search tool might need a query string and an optional result limit. Write each property with a type and a short description, and list only truly mandatory fields under required.

If you already have a sample call, you do not have to write the schema by hand. Paste a sample into the JSON schema generator to get a first draft, then tighten it: add descriptions, mark the required fields, and remove properties that only appeared in your one example.

Step 2: Format and read it like a reviewer

A schema that is hard to read is hard to review. Run the draft through the JSON formatter so the nesting is clear. Then ask three questions: could a model understand each description without seeing the code, does every required field really have to be present, and is any property so loose that it accepts nonsense?

Step 3: Test it with good and bad calls

A schema is only useful if it accepts the right input and rejects the wrong input. Keep a small set of sample payloads in two groups:

• Valid calls: the typical case, a call with only the required fields, and a call with every optional field.
• Invalid calls: a missing required field, a number where a string is expected, an extra unknown field, and an empty string.

Paste each payload and your schema into the JSON schema validator. The valid group should pass and the invalid group should fail with a message you understand. If a bad payload passes, the schema is too loose. If a good payload fails, the schema is too strict or the tool's real behaviour differs from what you wrote.

Step 4: Handle tools with no parameters

Some tools take nothing, such as a "get current time" tool. The draft specification recommends this form for a tool with no parameters, because it explicitly accepts only an empty object:

{ "type": "object", "additionalProperties": false }

The alternative, { "type": "object" }, accepts any object, including one with properties. Test both with the validator so you see the difference for yourself.

Step 5: Treat errors as part of the design

The draft describes two kinds of errors. Protocol errors cover things like an unknown tool or a malformed request. Tool execution errors, reported with isError: true in the result, cover problems such as a date in the wrong format or a value out of range, and the specification says clients should pass these to the model so it can correct itself. That means error messages are part of your interface. "Invalid departure date: must be in the future" helps a model retry; "error 400" does not.

The same page says servers must validate all tool inputs, apply access controls, rate limit calls and sanitize outputs, and that clients should log tool usage for audit purposes. A schema is the first layer of validation, not the only one.

Step 6: Keep the schema stable as the tool changes

When you change a tool, compare the old and new schema before you release it. The JSON diff tool shows added, removed and changed properties. Adding an optional field is usually safe. Renaming a field, making an optional field required, or narrowing a type can break callers, so treat those as breaking changes and version the tool name or announce the change.

If you need to pull one field out of a larger tool list, the JSON path tester lets you check a path expression against real output before you put it into code.

Step 7: Record what the agent actually did

A good schema tells you what a call should look like. A log tells you what it did look like. UrwaTools has a separate guide to keeping a readable audit log of AI agent tool calls with JSON, and a walkthrough for reading and debugging webhook payloads that uses the same formatting and comparison habits.

When a plain schema is not enough

Schemas and sample files work well while you have a handful of tools. When many people need to search runs, replay them or manage who can use which tool, you will want a proper orchestration or tracing platform. ProductListo's AI and ML guide lists agent frameworks such as LangChain, and its DevTools guide covers adjacent infrastructure. For workflow automation, see the listing for n8n. The ProductListo trend explainer MCP grows up: what the 2026 update means for buyers of AI agent tools covers the protocol changes in more detail.

Makers of agent tools can submit a tool to the ProductListo directory or ask about sponsored placements through its write for us page.

This article is general information for developers. Specifications change, so always check the current version of any standard you rely on.