mcp-chat-cards

Overview Schema Source Related Servers Discussions Admin

Create show/hide card

create_reveal_card

Build interactive cards with collapsible show/hide sections and show-all/hide-all buttons for step-by-step guides, FAQs, spoilers, and long reference material.

Instructions

Render a card of collapsible show/hide sections with show-all/hide-all buttons. Good for step-by-step guides, FAQs, spoilers, and long reference material. Put source in a section's code field rather than inline in text, so it renders as a monospace block with a copy button instead of a paragraph.

Input Schema

Name	Required	Description
`title`	Yes
`sections`	Yes
`subtitle`	No
`tutorTerms`	No	Educational tutor terms. The first occurrence of each term in the card's visible prose is underlined; hovering ~1.2s shows the tip and notifies the host so the model can follow up. Terms are matched once per card, longest first, and never inside code samples, tooltips, or another term's tip. Matching is CASE-SENSITIVE, so "PATH" does not attach its tip to a filesystem "path"; set caseInsensitive on a term to match any casing. Term and tip are PLAIN text.
`contextActions`	No	Right-click menu actions the model anticipates being useful. Choosing one sends its prompt to the conversation; use {{selection}} to include the user's selected text.

Output Schema

Name	Required	Description
`card`	Yes
`parts`	Yes	Split state, present on EVERY card result so one completeness check works for all card types. Cards that cannot split always report {current:1,total:1,hasMore:false}; create_markdown_card and create_code_tour_card pack oversized content into parts and can report more. Read hasMore rather than the card title to decide whether content was withheld.
`display`	No	Present only when the host is not mounting this server's MCP Apps template (see MCP_CHAT_CARDS_RENDER): the card ships as a ready-made visualizer widget instead.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.0.0-alpha.1.0.1Oct 17, 2026

addedOutput schema / properties / display

Added value: +{
+  "additionalProperties": false,
+  "description": "Present only when the host is not mounting this server's MCP Apps template (see MCP_CHAT_CARDS_RENDER): the card ships as a ready-made visualizer widget instead.",
+  "properties": {
+    "action": {
+      "description": "What the caller must do to put the card in front of the user",
+      "type": "string"
+    },
+    "loading_messages": {
+      "description": "show_widget loading_messages",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "shown": {
+      "description": "False: the user cannot see this card until action is taken",
+      "type": "boolean"
+    },
+    "title": {
+      "description": "show_widget title (snake_case)",
+      "type": "string"
+    },
+    "widget_code": {
+      "description": "show_widget widget_code, passed unchanged",
+      "type": "string"
+    }
+  },
+  "required": [
+    "shown",
+    "action",
+    "title",
+    "loading_messages",
+    "widget_code"
+  ],
+  "type": "object"
+}

Changed10 schema fields changedv0.1.3-alphaAug 21, 2026

removedInput schema / $schema

Removed value: -"http://json-schema.org/draft-07/schema#"

addedInput schema / properties / sections / items / properties / code

Added value: +{
+  "description": "Code sample shown with a copy button",
+  "type": "string"
+}

addedInput schema / properties / sections / items / properties / html / description
```
Added value: +"HTML content (sanitized)"
```

addedInput schema / properties / sections / items / properties / language

Added value: +{
+  "description": "Language for the code sample",
+  "type": "string"
+}

addedInput schema / properties / sections / items / properties / text / description
```
Added value: +"Plain text content; ``` fenced blocks become code blocks"
```

changedInput schema / properties / tutorTerms / description

Previous value: -"Educational tutor terms. The first occurrence of each term in the card's visible prose is underlined; hovering ~1.2s shows the tip and notifies the host so the model can follow up. Terms are matched once per card, longest first, and never inside code samples, tooltips, or another term's tip. Term and tip are PLAIN text."New value: +"Educational tutor terms. The first occurrence of each term in the card's visible prose is underlined; hovering ~1.2s shows the tip and notifies the host so the model can follow up. Terms are matched once per card, longest first, and never inside code samples, tooltips, or another term's tip. Matching is CASE-SENSITIVE, so \"PATH\" does not attach its tip to a filesystem \"path\"; set caseInsensitive on a term to match any casing. Term and tip are PLAIN text."

addedInput schema / properties / tutorTerms / items / properties / caseInsensitive

Added value: +{
+  "description": "Match the term regardless of letter case (default false)",
+  "type": "boolean"
+}

removedOutput schema / $schema

Removed value: -"http://json-schema.org/draft-07/schema#"

addedOutput schema / properties / parts

Added value: +{
+  "additionalProperties": false,
+  "description": "Split state, present on EVERY card result so one completeness check works for all card types. Cards that cannot split always report {current:1,total:1,hasMore:false}; create_markdown_card and create_code_tour_card pack oversized content into parts and can report more. Read hasMore rather than the card title to decide whether content was withheld.",
+  "properties": {
+    "current": {
+      "description": "Part number this result rendered (1-based)",
+      "type": "number"
+    },
+    "hasMore": {
+      "description": "True when content was withheld; call again with part: current + 1",
+      "type": "boolean"
+    },
+    "total": {
+      "description": "How many parts the content splits into",
+      "type": "number"
+    }
+  },
+  "required": [
+    "current",
+    "total",
+    "hasMore"
+  ],
+  "type": "object"
+}

changedOutput schema / required

Previous value: -[
-  "card"
-]New value: +[
+  "card",
+  "parts"
+]

Changed1 schema field changedv0.1.1-alphaAug 12, 2026

changedInput schema / properties / tutorTerms / description

Previous value: -"Educational tutor terms. Occurrences in the card are underlined; hovering ~1.2s shows the tip and notifies the host so the model can follow up."New value: +"Educational tutor terms. The first occurrence of each term in the card's visible prose is underlined; hovering ~1.2s shows the tip and notifies the host so the model can follow up. Terms are matched once per card, longest first, and never inside code samples, tooltips, or another term's tip. Term and tip are PLAIN text."

First observedv0.0.0-alphaAug 10, 2026

TDQS

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden. It does disclose a real render behavior (source placed in a section's code field becomes a monospace block with a copy button rather than a paragraph), which is useful. However it says nothing about permissions, size/length limits, sanitization of html, or other operational traits an agent would need.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, front-loaded with what renders first, then use cases, then a practical placement tip. Nothing is wasted, though the final tip is narrow enough that it slightly dilutes the otherwise clean 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?

An output schema exists, so return values need not be explained. The description covers the core capability plus one important param behavior, and the complex tutorTerms/contextActions params are richly documented in the schema. It is largely sufficient, with only sibling-routing detail missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is low (40%) so the description must compensate. It adds meaningful semantics for the code field (monospace rendering plus copy button) versus the text field, partially closing the gap. The remaining params (title, subtitle, and the 'open' behavior behind show-all/hide-all) get no explanation, and tutorTerms/contextActions rely entirely on their schema text.

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?

States a specific verb (Render) and a precise resource (a card of collapsible show/hide sections with show-all/hide-all buttons), which is clearly distinguishable from sibling card types like animation, chart, table, or markdown cards. An agent can identify this tool without opening sibling schemas.

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?

Gives concrete when-to-use guidance ('step-by-step guides, FAQs, spoilers, and long reference material'), which helps selection. It stops short of naming which sibling card to prefer for adjacent scenarios or any exclusion conditions, so it lacks explicit alternative routing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.