mcp-chat-cards

Overview Schema Source Related Servers Discussions Admin

Refine an efficient prompt

create_prompt_refine_card

Ask only the multiple-choice questions needed to close gaps in a prompt draft, using radios, checkboxes, free-text Other, up to 3 rounds, or skip if clear.

Instructions

Step 2 of the efficient-prompt flow: ask the fewest multiple-choice questions that close the gaps the gist left. Radios by default, checkboxes when several answers can be true at once; every question also gets a free-text "Other". At most 3 refine rounds - pass the round number so the card can say how many are left. Skip this step entirely when the gist is already clear enough to write the prompt.

Input Schema

Name	Required	Description
`round`	No	Which refine round this is, 1 to 3 (default 1)
`title`	No
`subtitle`	No
`questions`	Yes
`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"
+}

Addedv0.2.0-alphaAug 29, 2026

TDQS

A4/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 and does add real behavioral context: default radio widgets, checkbox mode when several answers are true, an always-present free-text 'Other', and a hard cap of 3 refine rounds. It doesn't say what happens to submitted answers or what the card renders/returns, but it discloses enough UI and lifecycle behavior to be usable.

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 the flow position, with no filler. The widget-behavior sentence is dense but each clause carries distinct information; slight trimming of the radios/checkboxes detail is conceivable, but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/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 no explanation, and the flow guidance is solid. However, for a 5-parameter tool with a nested `questions` array, several parameters (`title`, `subtitle`, `contextActions`) receive no semantic coverage anywhere, leaving the definition short of complete.

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 description coverage is 40%, so the description must compensate. It explains the `round` semantics ('how many are left') and maps onto the `questions`/`multiple`/`options` structure via the radios-vs-checkboxes and Other rules, but leaves `title`, `subtitle`, and `contextActions` entirely unexplained in both places.

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 gives a specific verb and resource ('ask the fewest multiple-choice questions that close the gaps the gist left') and explicitly positions itself as 'Step 2 of the efficient-prompt flow', which cleanly separates it from the sibling gist and efficient-prompt card tools. An agent can tell what this tool does and where it sits without opening the schema.

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 states clear usage context ('Step 2 of the efficient-prompt flow') and an explicit exclusion ('Skip this step entirely when the gist is already clear enough to write the prompt'), plus the round cap. It stops short of naming the concrete alternative tools (e.g. the gist card as step 1, the efficient-prompt card as step 3), so the routing is implied by flow position rather than explicit.

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