An agent asks a tool for an invoice total. The tool replies, “The total is $42.50.” A person can read that, but the next tool in the workflow needs a number and a currency code. Should it pull 42.50 out of the sentence and assume dollars? That is a fragile handoff.
MCP structured tool output gives the client a better option: a JSON value returned in structuredContent, with an optional outputSchema declared by the tool. The client can check the result before using it. This is about the data an MCP tool returns, not about forcing the language model to answer in JSON.
The core idea
A tool has an inputSchema describing what it accepts. It can also declare an outputSchema describing the shape of its structured result. When the client invokes that tool, the server can return a machine-readable value in structuredContent alongside ordinary content blocks.
Consider a billing lookup that returns this value:
{
"invoice_id": "inv_123",
"amount_minor": 4250,
"currency": "USD",
"status": "open"
}The field name amount_minor makes the unit explicit. The client need not guess whether 42.50 means dollars, cents, or a formatted string. An output schema can require those fields and constrain their types. It cannot, by itself, prove that the invoice is real or that the caller is authorized to pay it.
How it works
First, a client discovers the tool with tools/list. Its definition may include both input and output schemas. This example leaves out transport and request metadata to focus on the tool definition:
{
"name": "get_invoice",
"description": "Retrieve an invoice by ID without changing it",
"inputSchema": {
"type": "object",
"properties": { "invoice_id": { "type": "string" } },
"required": ["invoice_id"]
},
"outputSchema": {
"type": "object",
"properties": {
"invoice_id": { "type": "string" },
"amount_minor": { "type": "integer" },
"currency": { "type": "string" },
"status": { "type": "string" }
},
"required": ["invoice_id", "amount_minor", "currency", "status"]
}
}After a tools/call, the relevant part of a successful tool result could look like this:
{
"content": [
{
"type": "text",
"text": "{\"invoice_id\":\"inv_123\",\"amount_minor\":4250,\"currency\":\"USD\",\"status\":\"open\"}"
}
],
"structuredContent": {
"invoice_id": "inv_123",
"amount_minor": 4250,
"currency": "USD",
"status": "open"
}
}The text block is there for clients that consume ordinary tool content. The structured field is what a program should inspect. Under the July 2026 MCP tools specification, servers with an output schema must return structured results that conform to it; clients should validate them. The specification also recommends returning serialized JSON in a text block for backward compatibility.
One version detail matters if you support older clients. The November 2025 tools specification restricted structured content to JSON objects. The July 2026 revision permits any JSON value, including an array, string, number, boolean, or null, as long as it matches the declared schema. If your client and server negotiate an older protocol revision, do not assume a top-level array will work. An object-shaped result is the safer cross-version choice.
Why it matters for AI agents
Agents often pass one tool’s output into another. An agent might retrieve an invoice, check its status, then prepare a payment request for a human to approve. A prose result makes the agent infer types and units. A validated structured result lets application code reject a missing currency field or an amount_minor returned as a string before anything downstream acts on it.
That does not make tool output trustworthy on its own. Schema validation checks shape, not provenance, permission, correctness, or whether a string contains hostile instructions. Treat returned values as external data. Keep approval and authorization checks around consequential actions. See MCP auth and our guide to treating tool results as data for the other half of this design.
Structured output in practice
Start with a read-only tool whose result another part of your application already needs to parse. Name fields after their actual units, make required fields truly required, and document nullable or absent values deliberately. Validate the server result against the advertised schema in a client-side test. Test a missing field, a wrong type, and a real tool failure, not just the happy path.
Keep business rules separate. A schema can say status is a string; your application still has to decide whether open is payable. The schema can constrain allowed values, but it cannot tell you whether a payment should be made. If a workflow crosses accounts or spends money, require the appropriate authorization and user approval before the write.
Do not replace the text block solely because your own client understands structuredContent. Other clients may still read content. And if you publish a tool to an MCP server directory, describe both the inputs and the returned fields so developers can tell whether the tool fits their workflow before installing it.
FAQ
Is structuredContent the same thing as a model’s JSON mode?
No. It is server-produced tool result data. Model JSON mode constrains a model-generated response. A tool result comes from the server, and clients can validate it against the tool’s declared output schema.
Does every MCP tool need an output schema?
No. The output schema is optional. It helps when code or another tool needs a predictable value. A tool that returns a varied document or image may be better served by ordinary content blocks.
Can a client skip validation because the server declared a schema?
It should not. A declared schema is a contract, not evidence that every response follows it. Validate before passing fields into another operation, and handle failures explicitly.
Can structured output include an array at the top level?
Yes under the July 2026 specification, if it matches the schema. Older protocol revisions used object-shaped structured content. Check the negotiated revision when you need compatibility across clients.