mcp-chat-cards

Overview Schema Source Related Servers Discussions Admin

Create document card from markdown

create_markdown_card

Render markdown content or files as interactive chat cards with card tables, code copy buttons, and foldable H2 sections; long docs split into parts.

Instructions

Render a markdown document as one interactive card: tables become card tables, fenced code gets copy buttons, and H2 sections fold into show/hide reveals. Pass either the markdown content or the path of a markdown file generated earlier in the conversation (for example a walkthrough or guide) to plug it into the chat in one call. Raw HTML in the markdown is NOT rendered as markup: it is shown as literal text, the same as in every other card's text fields, so use markdown syntax for formatting. Long documents split at H2 boundaries into parts of about 32,000 rendered characters each; the result's structuredContent.parts {current,total,hasMore} says whether more parts remain. A document with no H2 headings cannot be split and renders as one part.

Input Schema

Name	Required	Description
`part`	No	Part number for large documents (1-based). Long documents split automatically; while structuredContent.parts.hasMore is true, call again with the next part.
`path`	No	Path to a markdown file ON THE MACHINE RUNNING THIS SERVER, not in the caller's sandbox. Over a remote bridge those are different machines: if the file exists only on your side, pass its text as markdown instead.
`title`	No	Card title; defaults to the document's first H1
`markdown`	No	Markdown content to render
`subtitle`	No
`openFirst`	No	Open the first section initially (default true)
`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.
`splitSections`	No	Fold H2 sections into reveals (default true)
`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"
+}

Changed7 schema fields changedv0.1.3-alphaAug 21, 2026

removedInput schema / $schema

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

changedInput schema / properties / part / description

Previous value: -"Part number for large documents (1-based). Long documents split automatically; when the result says more parts remain, call again with the next part."New value: +"Part number for large documents (1-based). Long documents split automatically; while structuredContent.parts.hasMore is true, call again with the next part."

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"
+]

Changed2 schema fields changedv0.1.1-alphaAug 12, 2026

changedInput schema / properties / path / description

Previous value: -"Path to a local markdown file to render instead"New value: +"Path to a markdown file ON THE MACHINE RUNNING THIS SERVER, not in the caller's sandbox. Over a remote bridge those are different machines: if the file exists only on your side, pass its text as markdown instead."

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

A4.6/5.0

Behavior5/5

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

With no annotations provided, the description carries the full burden and does so well: it discloses that raw HTML renders as literal text, that long documents split at H2 boundaries into ~32,000-character parts, how to detect more parts via structuredContent.parts.hasMore, and that documents without H2 headings cannot be split. These are non-obvious behavioral traits an agent would otherwise discover only by trial and error.

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?

The purpose and rendering behavior are front-loaded, and each subsequent sentence covers a distinct concern (input choice, HTML handling, splitting, no-H2 edge case) with no filler. It is slightly long for a single paragraph but every sentence 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?

For a 9-parameter tool with no required parameters and an output schema that handles return values, the description covers everything an agent needs: rendering semantics, input source caveats, pagination behavior, and the HTML limitation. Nothing material is left to inference.

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?

Schema description coverage is high (89%), so the baseline is 3 and the description only needs to add marginal value. It does: it explains the interaction between the `part` parameter and the automatic splitting/hasMore flow, and ties H2 folding to splitSections, adding cross-parameter semantics the schema documents only in isolation.

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 opens with a specific verb+resource: 'Render a markdown document as one interactive card', then immediately enumerates the concrete rendering behaviors (tables, code copy buttons, H2 folding). This clearly separates it from siblings like create_table_card or create_code_tour_card, which would render those elements standalone rather than as parts of one markdown document.

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?

It tells the agent which inputs are acceptable and where content should come from: 'Pass either the markdown content or the path of a markdown file generated earlier in the conversation (for example a walkthrough or guide)'. The schema further warns about the path-vs-sandbox distinction. However, there is no explicit when-to-use-this-vs-a-sibling guidance (e.g. when to prefer create_table_card over a markdown table), which would be needed for a 5.

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