Skip to main content
Glama
cchadha2

mcp-response-types-lab

by cchadha2

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 return structuredContent conforming to it.

  • For backwards compatibility, the spec recommends servers that return structuredContent also return a serialized-JSON text block in content, so pre-2025-06-18 clients still get something.

  • The spec says clients SHOULD validate structuredContent against outputSchema when 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_schema__text_only

no

text

no_schema__structured_only

no

[]

present

no_schema__text_and_structured

no

text

present, matches text

with_schema__text_and_structured_matching

yes

text

present, matches text and schema

with_schema__structured_only_no_text

yes

[]

present, matches schema

with_schema__text_and_structured_mismatched

yes

text says price $25, in stock

structuredContent says price $9.99, out of stock

with_schema__structured_violates_schema

yes

text

present but violates schema (missing required field, wrong types)

with_schema__structured_missing

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 boolean

with_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 content

So 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 build

Node 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 below

Cert 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.js

Opens 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:

/mcp

to 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/mcp

To 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 structuredContent object (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

no_schema__text_only

content text only

text: "Widget costs $9.99 and is currently out of stock."

text: "Widget costs $9.99 and is currently out of stock."

text: "Widget costs $9.99 and is currently out of stock."

no_schema__structured_only

structuredContent only, content: []

JSON: {"name":"Widget","price":9.99,"in_stock":false}

JSON: {"name":"Widget","price":9.99,"in_stock":false}

JSON: {"name":"Widget","price":9.99,"in_stock":false}

no_schema__text_and_structured

both present in envelope

text: "Widget costs $9.99 and is currently out of stock." (JSON not shown)

text: "Widget costs $9.99 and is currently out of stock." (JSON not shown)

JSON: {"name":"Widget","price":9.99,"in_stock":false} (text not shown)

with_schema__text_and_structured_matching

both present in envelope

text: "Widget costs $9.99 and is currently out of stock."

text: "Widget costs $9.99 and is currently out of stock."

JSON: {"name":"Widget","price":9.99,"in_stock":false}

with_schema__structured_only_no_text

structuredContent only, content: []

JSON: {"name":"Widget","price":9.99,"in_stock":false}

JSON: {"name":"Widget","price":9.99,"in_stock":false}

JSON: {"name":"Widget","price":9.99,"in_stock":false}

with_schema__text_and_structured_mismatched

both present, unreconciled (text says $25/in stock, structuredContent says $9.99/out of stock)

text: "Widget costs $25.00 and is in stock."

text: "Widget costs $25.00 and is in stock."

JSON: {"name":"Widget","price":9.99,"in_stock":false}

with_schema__structured_violates_schema

call rejected client-side, JSON-RPC -32602

text: "Widget costs twenty-five dollars, in stock: yes" (server's bad text, but no error)

text: "Widget costs twenty-five dollars, in stock: yes" (server's bad text, but no error)

malformed JSON passed through: {"price":"twenty-five dollars","in_stock":"yes"} (no error)

with_schema__structured_missing

call rejected client-side, JSON-RPC -32600

text: "Widget costs $9.99 and is currently out of stock." (no error)

text: "Widget costs $9.99 and is currently out of stock." (no error)

text: "Widget costs $9.99 and is currently out of stock." (no error)

Key findings

  1. Text-vs-structured preference is inconsistent even within Anthropic's own surfaces. Claude Desktop and claude.ai's native chat both prefer content text when both fields are present — they never showed structuredContent unless content was empty. Claude Code, hitting the same connector, does the opposite: it prefers structuredContent whenever 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.

  2. outputSchema is not enforced by any of the three real clients. The deliberately-invalid structuredContent (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 reference Client() class (as used by mcp-inspector) validates client-side and refuses the call outright (-32602 for a schema violation, -32600 when outputSchema is declared but structuredContent is missing).

  3. Practical takeaway: write content text as a complete, standalone answer — don't assume a client will read structuredContent instead of or in addition to it. And don't rely on outputSchema to catch a server bug before it reaches a client; validate structuredContent yourself 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 tools
no_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.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose4/5

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.

Usage Guidelines3/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.2/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.1/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines2/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
nameYes
priceYes
in_stockYes

TDQS

A4.7/5.0
Behavior5/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
nameYes
priceYes
in_stockYes

TDQS

A4.4/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
nameYes
priceYes
in_stockYes

TDQS

A4.4/5.0
Behavior5/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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).

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
nameYes
priceYes
in_stockYes

TDQS

A3.7/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose4/5

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.

Usage Guidelines3/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
nameYes
priceYes
in_stockYes

TDQS

A4.4/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

  1. 8 tool updatesv0.1.0
    • First observedno_schema__structured_only
    • First observedno_schema__text_and_structured
    • First observedno_schema__text_only
    • First observedwith_schema__structured_missing
    • First observedwith_schema__structured_only_no_text
    • First observedwith_schema__structured_violates_schema
    • First observedwith_schema__text_and_structured_matching
    • First observedwith_schema__text_and_structured_mismatched

TDQS

A4.3/5.0

Scored across 8 tools

Disambiguation5/5

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.

Naming Consistency5/5

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.

Tool Count5/5

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.

Completeness5/5

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

ActivitySlowing
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers