mcp-response-types-lab
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-response-types-labRun the with_schema__text_and_structured_mismatched tool"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-response-types-lab
A local MCP server (protocol 2025-06-18) purpose-built to answer one question:
when a tool result carries both content and structuredContent, which one
do different MCP clients actually use — and does that change if the tool
declares an outputSchema?
Background (2025-06-18 spec)
CallToolResult.content— an array of content blocks (text/image/audio/ resource). Required, but MAY be empty ([]).CallToolResult.structuredContent— optional arbitrary JSON object.Tool.outputSchema— optional JSON Schema. If a tool declares one, the spec says the server MUST returnstructuredContentconforming to it.For backwards compatibility, the spec recommends servers that return
structuredContentalso return a serialized-JSON text block incontent, so pre-2025-06-18 clients still get something.The spec says clients SHOULD validate
structuredContentagainstoutputSchemawhen present.
None of that says what a client does with the model-facing context when both are present, what a user-facing UI renders, or what happens on a schema violation — that's what this lab is for.
Related MCP server: mcp-apps-office-kit
The tool matrix
Every tool takes no arguments. Names encode the two variables under test:
no_schema__* (tool has no outputSchema) vs with_schema__* (it does),
followed by what content/structuredContent combination is returned.
Tool | outputSchema | content | structuredContent |
| no | text | — |
| no |
| present |
| no | text | present, matches text |
| yes | text | present, matches text and schema |
| yes |
| present, matches schema |
| yes | text says price $25, in stock | structuredContent says price $9.99, out of stock |
| yes | text | present but violates schema (missing required field, wrong types) |
| yes | text | absent, despite schema being declared |
Source: src/server.ts. Add more variants there if you find a client-specific
edge case worth isolating — keep the naming convention so results stay
diffable.
Baseline: raw server responses (via mcp-inspector CLI)
Before testing any chat client, every tool was called directly against the
server over stdio using @modelcontextprotocol/inspector --cli — this uses
the official TS SDK's Client class with no vendor UI logic on top, so it's
the ground truth for what actually goes over the wire. Command used for each:
npx @modelcontextprotocol/inspector --cli node dist/server.js \
--method tools/call --tool-name <tool_name>no_schema__text_only
{
"content": [
{ "type": "text", "text": "Widget costs $9.99 and is currently out of stock." }
]
}no_schema__structured_only
{
"content": [],
"structuredContent": { "name": "Widget", "price": 9.99, "in_stock": false }
}no_schema__text_and_structured
{
"content": [
{ "type": "text", "text": "Widget costs $9.99 and is currently out of stock." }
],
"structuredContent": { "name": "Widget", "price": 9.99, "in_stock": false }
}with_schema__text_and_structured_matching
{
"content": [
{ "type": "text", "text": "Widget costs $9.99 and is currently out of stock." }
],
"structuredContent": { "name": "Widget", "price": 9.99, "in_stock": false }
}with_schema__structured_only_no_text
{
"content": [],
"structuredContent": { "name": "Widget", "price": 9.99, "in_stock": false }
}with_schema__text_and_structured_mismatched — text and structuredContent
deliberately disagree:
{
"content": [
{ "type": "text", "text": "Widget costs $25.00 and is in stock." }
],
"structuredContent": { "name": "Widget", "price": 9.99, "in_stock": false }
}with_schema__structured_violates_schema — server tried to return
{"price":"twenty-five dollars","in_stock":"yes"} (missing required name,
wrong types), but the call never succeeds. mcp-inspector rejects it
client-side before returning anything to the caller:
Failed to call tool with_schema__structured_violates_schema: MCP error -32602:
Structured content does not match the tool's output schema: data must have
required property 'name', data/price must be number, data/in_stock must be booleanwith_schema__structured_missing — server declared outputSchema but
returned only text, no structuredContent. Also rejected client-side:
Failed to call tool with_schema__structured_missing: MCP error -32600:
Tool with_schema__structured_missing has an output schema but did not return
structured contentSo for any client built on the official SDK's Client class, outputSchema
isn't just documentation — the client actively enforces it and refuses to
hand a malformed or incomplete result to the caller at all. Whether Claude
Code / Desktop / claude.ai run that same validation path, or roll their own
handling, is what the client comparison below checks.
Setup
npm install
npm run buildNode version note: this machine's default node (Homebrew 18.11.0) is
currently broken — dyld: Library not loaded: libicui18n.71.dylib — because
a later brew upgrade moved icu4c out from under it. It has nothing to do
with this project, but it will silently break any tool here that shells out
to node. A working Node 20 was installed alongside it (brew install node@20, keg-only, does not touch the default node symlink). All commands
below use it explicitly:
export PATH="/opt/homebrew/opt/node@20/bin:$PATH"
export NODE_EXTRA_CA_CERTS=/etc/ssl/cert.pem # see note belowCert note: Node 18.11's bundled CA store can't validate npm's current
TLS chain (UNABLE_TO_GET_ISSUER_CERT_LOCALLY) even though curl works
fine using the system store. Pointing NODE_EXTRA_CA_CERTS at the system
bundle (/etc/ssl/cert.pem) fixes npm install. Only needed for install /
running the inspector via npx; the built server itself makes no network
calls.
Testing each client
1. mcp-inspector (reference client / GUI)
export PATH="/opt/homebrew/opt/node@20/bin:$PATH"
npx @modelcontextprotocol/inspector node dist/server.jsOpens a local web UI. Call each tool, note what the "Structured Content" and "Content" panes show, and whether schema-violating calls are blocked in the UI (they are, per the CLI results above) or just visually flagged.
CLI form (no UI, scriptable), one tool at a time:
npx @modelcontextprotocol/inspector --cli node dist/server.js \
--method tools/call --tool-name <tool_name>2. Claude Code (this CLI)
Already registered at project scope — see .mcp.json. From an interactive
claude session in this repo:
/mcpto confirm response-types-lab is connected, then ask Claude to call each
of the 8 tools by name and report back verbatim what it received in
content vs structuredContent, and whether any call errored. Because I
(this background session) can't hot-reload newly-registered MCP servers
into my own running process, this step needs a fresh interactive session —
I can't self-report Claude Code's live behavior from here.
3. Claude Desktop
Installed on this Mac but not something I can drive (no GUI access from a
background job). Add to Desktop's config —
~/Library/Application Support/Claude/claude_desktop_config.json — merging
in:
{
"mcpServers": {
"response-types-lab": {
"command": "/opt/homebrew/opt/node@20/bin/node",
"args": ["/Users/chiragchadha/Code/mcp-response-types-lab/dist/server.js"]
}
}
}Fully restart Claude Desktop (quit, not just close the window), then in a
chat ask it to call each tool and report what it saw. Also worth eyeballing
the UI directly — does it render a distinct "structured data" view, a raw
JSON block, or nothing when content is empty?
4. claude.ai / Claude Mobile
Both only connect to remote MCP servers (HTTP transport with OAuth), not local stdio processes. The server already supports Streamable HTTP:
export PATH="/opt/homebrew/opt/node@20/bin:$PATH"
MCP_TRANSPORT=http npm start # listens on http://localhost:3939/mcpTo reach it from claude.ai or mobile you'd need to expose that port
publicly (e.g. ngrok http 3939 or cloudflared tunnel). I haven't done
this — it means opening this machine's server to the internet, even if
briefly, so it's your call whether/how to do it. Say the word and I'll wire
up a tunnel and walk through adding it as a custom connector in
claude.ai's settings; otherwise this is a manual step for you.
Results (captured 2026-08-11)
Tested against the deployed MCP_TRANSPORT=http server via a Cloudflare
quick tunnel, added as a custom connector on claude.ai (name
response-types-lab). Claude Desktop's and Claude Code's results below are
both reached through that same connector — Desktop natively, Claude Code via
the claude.ai account-connector bridge (shows up prefixed claude.ai response-types-lab in its tool-call log) — so this is one server, three
different client-side handling layers.
The two possible outcomes below, spelled out so the table cells are unambiguous:
text = the model was shown the human-readable sentence from
content(e.g."Widget costs $9.99 and is currently out of stock.")JSON = the model was shown the raw
structuredContentobject (e.g.{"name":"Widget","price":9.99,"in_stock":false}), not a sentence
The mcp-inspector column shows the actual raw wire response instead (it's not a chat client, so there's no "which one wins" decision to observe — see the full payloads above).
Tool | mcp-inspector (raw wire) | Claude Desktop showed | claude.ai showed | Claude Code showed |
|
| text: | text: | text: |
|
| JSON: | JSON: | JSON: |
| both present in envelope | text: | text: | JSON: |
| both present in envelope | text: | text: | JSON: |
|
| JSON: | JSON: | JSON: |
| both present, unreconciled (text says $25/in stock, structuredContent says $9.99/out of stock) | text: | text: | JSON: |
| call rejected client-side, JSON-RPC | text: | text: | malformed JSON passed through: |
| call rejected client-side, JSON-RPC | text: | text: | text: |
Key findings
Text-vs-structured preference is inconsistent even within Anthropic's own surfaces. Claude Desktop and claude.ai's native chat both prefer
contenttext when both fields are present — they never showedstructuredContentunlesscontentwas empty. Claude Code, hitting the same connector, does the opposite: it prefersstructuredContentwhenever present, even over conflicting text. On the mismatched-values tool the two groups showed genuinely different numbers to the model/user for an identical server response.outputSchemais not enforced by any of the three real clients. The deliberately-invalidstructuredContent(string where a number was required, missing required field) passed through untouched on Desktop, claude.ai, and Claude Code — no validation error, no rejection. Only the bare referenceClient()class (as used by mcp-inspector) validates client-side and refuses the call outright (-32602for a schema violation,-32600whenoutputSchemais declared butstructuredContentis missing).Practical takeaway: write
contenttext as a complete, standalone answer — don't assume a client will readstructuredContentinstead of or in addition to it. And don't rely onoutputSchemato catch a server bug before it reaches a client; validatestructuredContentyourself before returning it.
Not yet tested: Claude Mobile (should inherit claude.ai's account connectors — worth a quick spot check to confirm it matches claude.ai's native behavior rather than Claude Code's).
Available Tools
8 toolsno_schema__structured_onlyA
No outputSchema declared, but the result carries structuredContent and an EMPTY content array. Tests whether a client that never saw an outputSchema will still surface structuredContent, or shows nothing because content is empty.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the burden of behavioral disclosure. It accurately describes the absence of outputSchema, the presence of structuredContent, and the empty content array, which is the core behavior being tested. This is precise and useful for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the key fact (no outputSchema declared) and immediately explains the test's intent. Every word earns its place; there is no waste or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (zero params, no schema), the description fully explains the scenario and the expected client behavior. The sibling list provides additional context that this is one of several test scenarios, and the description is complete for its purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema provides complete information. The description does not add parameter details, but none are needed. This matches the baseline for no-parameter tools, and the lack of additional info is not a gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to test whether a client will surface structuredContent when no outputSchema is declared, given an empty content array. It is specific to the tool's role in a test suite, though it does not explicitly distinguish itself from sibling tools by name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage as part of a set of scenario tests for structuredContent handling, but it does not explicitly state when to use this tool versus its siblings. The purpose is clear from context, but no direct alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
no_schema__text_and_structuredA
No outputSchema declared, but the result carries BOTH a text content block and structuredContent (matching values). Tests whether structuredContent is used opportunistically even without a declared schema.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations available, the description carries the burden, and it discloses key behavioral traits: the lack of an output schema, the dual nature of the result (text + structured), and the fact that values match. It also reveals the testing intent, which is a useful behavioral insight beyond what schema/annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is direct and information-dense. It front-loads the most critical fact (no outputSchema) and clearly conveys the tool's purpose without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no parameters and no output schema, the description adequately covers the essential behaviors: the presence of both text and structured content, the matching values, and the opportunistic usage test. It does not describe the actual content values, but that is not necessary given the tool's purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description appropriately does not need to explain parameter semantics, and the empty schema confirms no parameters exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: it tests whether structuredContent is used opportunistically when no output schema is declared. It also specifies the distinct behavior of returning both a text block and structuredContent, distinguishing it from siblings like no_schema__text_only and no_schema__structured_only.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than explicit. The description explains what the tool does, but does not directly state when to choose this tool over its siblings or provide exclusion criteria. The sibling names suggest a test matrix, but no explicit guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
no_schema__text_onlyA
No outputSchema. Returns a plain text content block only. This is the pre-2025-06-18 baseline.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It clearly discloses that output is plain text only and confirms the absence of an output schema. This gives the agent essential information about the tool's behavior, though it does not elaborate on side effects or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core behavior. 'No outputSchema' and 'Returns a plain text content block only' are direct. The baseline context sentence adds useful historical information without redundancy. Extremely concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters, no annotations, and no output schema, the description is complete. It specifies the return type and the absence of schema, covering all relevant behavioral details. The simple nature of the tool means nothing else is required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema is empty. The description does not need to add parameter meaning since none exist. Per the baseline rule for 0 params, a score of 4 is appropriate; the description does not detract from this.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Returns a plain text content block only.' It explicitly notes 'No outputSchema,' which distinguishes it from sibling tools that include structured output. The behavior is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lacks explicit guidance on when to use this tool versus alternatives. It only mentions 'This is the pre-2025-06-18 baseline,' which is historical context but does not explain USE cases or exclusions. No alternatives or preferred scenarios are indicated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
with_schema__structured_missingA
outputSchema declared, but the result omits structuredContent entirely (only text content is returned) — a non-compliant server. Tests client behavior when a promised schema is never fulfilled.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| name | Yes | |
| price | Yes | |
| in_stock | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It explicitly discloses the non-compliant behavior: structuredContent is omitted despite the output schema declaration. This is exactly what an agent needs to know.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, dense sentence conveys the purpose, the behavioral anomaly, and the testing intent. No wasted words; every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (no params, no nested schema), the description is fully complete. It explains the scenario, the server's non-compliance, and the expected client behavior test.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the description adds no parameter information. The baseline for 0 params is 4, and there is no deficit to compensate for.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific behavior: the tool declares an output schema but returns only text content without structuredContent. This is a well-defined test scenario that distinguishes it from sibling tools, which cover other schema/structuredContent permutations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: to test client behavior when a promised schema is never fulfilled. While it does not explicitly name alternatives, the sibling tool names indicate related scenarios, and the intent is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
with_schema__structured_only_no_textA
outputSchema declared. Returns structuredContent with an EMPTY content array (no text fallback). Tests whether the client/model can operate on structuredContent alone.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| name | Yes | |
| price | Yes | |
| in_stock | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It explicitly discloses that the content array is empty, there is no text fallback, and the return type is structuredContent. It also notes that an outputSchema is declared. This goes beyond minimal disclosure by specifying exact return behavior, though it does not mention edge cases or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the key behavioral detail (empty content array, no text fallback) and the testing purpose. Every sentence earns its place; there is no waste or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no parameters and an output schema, so the description does not need to detail return values (schema handles that). It covers the purpose, the specific structuredContent behavior, and the testing context. It is complete for a simple test tool, though it could mention expected usage as a client/model capability check more explicitly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the baseline is 4. The description does not need to add parameter information because the input schema is empty and coverage is 100%. No additional parameter semantics are required or missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool does: it returns structuredContent with an EMPTY content array and no text fallback. This is a specific verb ('Returns') plus a resource ('structuredContent') and a distinguishing characteristic (no text fallback), effectively separating it from siblings like text_and_structured variants.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear usage context: 'Tests whether the client/model can operate on structuredContent alone.' This implies when to use the tool (for testing structuredContent-only handling). However, it does not explicitly mention alternatives or when not to use it, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
with_schema__structured_violates_schemaA
outputSchema declared, but the returned structuredContent violates it (wrong types, missing required field). Tests whether the client validates structuredContent against outputSchema and how it fails.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| name | Yes | |
| price | Yes | |
| in_stock | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full behavioral disclosure. It explicitly discloses that the tool returns structuredContent with wrong types and a missing required field, and that its purpose is to test client validation. This is complete transparency for a deliberately faulty test tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the key behavior (violates schema) and its testing purpose. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter test tool, the description adequately explains its purpose and expected behavior. It does not detail the exact output schema structure, but that is irrelevant to the tool's intent. The sister-tool naming adds context, making this description sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so schema coverage is complete and the baseline is 4. The description adds no parameter-specific semantics, but none are needed since there are no inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's specific function: it declares an outputSchema but returns structuredContent that violates it, testing client validation behavior. This distinguishes it from sibling test tools by the specific kind of violation it introduces.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool's intended use as a test case for validation failure, but it does not explicitly contrast it with sibling tools or state when to use it versus alternatives. The purpose is clear enough, but usage guidance is implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
with_schema__text_and_structured_matchingA
outputSchema declared. Returns matching text + structuredContent (the spec's recommended backward-compatible pattern).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| name | Yes | |
| price | Yes | |
| in_stock | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosure. It discloses that the tool returns both text and structuredContent, and that they are 'matching'. It does not describe side effects, permissions, or error behavior, but for a zero-parameter tool this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the key behavior, and contains no wasted words. It efficiently conveys the essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and an output schema is declared, the description sufficiently covers the behavior. It could mention the tool's demonstrative purpose, but the sibling names and context make it clear enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and the schema is empty, so there is no parameter information to convey. Per the baseline for 0 params, the description need not elaborate, and it does not obstruct understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool 'Returns matching text + structuredContent', which clearly indicates the output format and behavior. It distinguishes from siblings by specifying 'matching', implying alignment with the spec, unlike 'with_schema__text_and_structured_mismatched'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'the spec's recommended backward-compatible pattern' implies this tool is the preferred choice among alternatives, but it does not explicitly state when to use it or mention exclusions. Usage guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
with_schema__text_and_structured_mismatchedA
outputSchema declared. Text content and structuredContent DISAGREE on the actual values. Tests which one the client actually feeds to the model / shows the user.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| name | Yes | |
| price | Yes | |
| in_stock | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the core behavioral trait: text and structuredContent are intentionally set to disagree to probe client behavior. The mention of 'outputSchema declared' also informs the agent that the tool expects a schema to be present. It could add more detail about return values, but the output schema covers that, so this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that clearly communicates the scenario and the test objective. Every phrase is informative: 'outputSchema declared', 'DISAGREE', and 'Tests which one the client actually feeds to the model / shows the user.' No waste, excellent structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no params) and presence of an output schema, the description is largely complete. It explains the deliberate mismatch and the testing purpose. It could be slightly more explicit about the expected outputs, but the output schema already documents those. The sibling context further clarifies the test suite role.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description does not need to explain any parameters, and the empty schema confirms no inputs are required. No additional param semantics are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: it tests which content source (text vs structuredContent) the client actually uses when they disagree. The verb 'Tests' plus the specific resource ('which one the client actually feeds to the model / shows the user') makes the intent unambiguous. It also distinguishes itself from siblings (e.g., matching variant) by explicitly highlighting the mismatch scenario.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool by explaining it tests a specific client behavior under disagreement. While it does not name alternatives or explicitly state 'use this instead of...', the context of siblings and the clear purpose provide sufficient usage guidance. No exclusions are given, but the test scenario is well-defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
8 tool updates
v0.1.0- First observed
no_schema__structured_only - First observed
no_schema__text_and_structured - First observed
no_schema__text_only - First observed
with_schema__structured_missing - First observed
with_schema__structured_only_no_text - First observed
with_schema__structured_violates_schema - First observed
with_schema__text_and_structured_matching - First observed
with_schema__text_and_structured_mismatched
TDQS
Scored across 8 tools
Each tool targets a distinct response-type scenario (schema presence × content composition), with descriptions that clearly differentiate matching, mismatched, missing, and violating structured content. No two tools are functionally interchangeable.
All tool names follow a uniform pattern: [with_schema|no_schema]__[content description]. The consistent use of double underscores and ordered descriptors makes the naming scheme predictable and scannable.
8 tools is well-scoped for a response-types lab, covering the combinatorial space of schema declarations and text/structured content variations without redundancy or bloat.
The tool set covers the major response-type permutations: no schema (text-only, structured-only, both), with schema (matching, mismatched, structured-only, schema violation, missing structured content). This is a thorough and coherent test surface for the lab's purpose.
Maintenance
Related MCP Connectors
One MCP endpoint for Claude, GPT & Gemini: 100+ tools + no-code connectors + agent workers.
Remote MCP for C2PA intake verifier MCP, structured receipts, audit logs, and reviewer-ready evidenc
Remote MCP for Gemini upgrade evals, prompt regressions, output diffs, and eval receipts.
Hosted MCP catalog with 30 tenant-isolated browser, RAG, AI, mail and media tools.
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceEnables image generation, editing, and blending using Gemini 2.5 Flash capabilities, plus text generation for AI-powered creative workflows through MCP tools.MIT
- FlicenseNot gradedqualityDmaintenanceEnables LLM Desktop clients to generate rich media content like PPT, HTML, and flowcharts via Canvas Core and MCP Apps extension mechanism.-
- FlicenseNot gradedqualityBmaintenanceExposes a deterministic AI-slop scanner and RAG grounding grader as MCP Tools, Resource, and Prompt, enabling any MCP client to evaluate text quality and context faithfulness.-
- AlicenseNot gradedqualityBmaintenanceHosted MCP server for structured knowledge extraction and entity enrichment, allowing users to author JSON schemas, enrich entities using multiple LLM providers, and benchmark model performance.MIT