Clarifo

generate_visual_cards

Read-onlyIdempotent

Validate and render a VisualStoryContent v2 story that you authored into PNG cards. No LLM call: you write the cards from the analysis you already have; Clarifo enforces structure, palettes, chart specs and colours deterministically and drops invalid fields.

Call get_visual_cards_guide ONCE before authoring (skip only when re-rendering a story you just authored with it); without it stories routinely get the wrong templateId, no mode or no cover card.

Story format (essentials; the guide has the full spec): Top level: company, period, industry, palette (graphite_navy | deep_green | midnight_teal | burgundy | graphite | bone), language, numberFormat, cards (4-7; first = cover). Card: headline (required, <= 12 words), category, deck, lede, source, stat, chart, mode (A | B | C), templateId, stats (<= 4), segments, extraCharts (<= 2), quote, annotations (<= 6). Chart types: line, area, bar, stacked_bar, bar_line_combo, waterfall, donut, world_map, table, process_steps, radial_gauge and more. Never invent image URLs.

Args: visual_story_content: The story; must contain a non-empty cards list. company / period / industry / palette / language: Optional overrides of the story's own fields. aspect: "1:1" (default), "4:5", "9:16", "4:3" or "16:9" (landscape layout); invalid values fall back to "1:1".

Returns: Normally a JSON summary plus one PNG image per card. Show the returned images inline as the result; do not redraw them. The summary carries visuals[] (visual_id, title, placement_hint, image_index), visual_order, render_url and the validated story. When the images are not visible to the user (e.g. ChatGPT, or a collapsed tool panel), share render_url as a link: it opens the same cards on clarifo.com. Never write placeholder text such as "[Insert chart here]"; refer to the visuals in the narrative. If render_qa is present, apply its hint fixes and call again. Without headless rendering: the same metadata plus artifact_html. On error: {"error", "failure_kind"}.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "visual_story_content": "<visual_story_content>"
    },
    "name": "generate_visual_cards"
  }
}

Input Schema

Name	Required	Description	Default
`aspect`	No
`period`	No
`company`	No
`palette`	No
`industry`	No
`language`	No
`visual_story_content`	Yes

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 9, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, and the description goes well beyond them: deterministic enforcement of palettes, chart specs and colours, silent dropping of invalid fields, invalid aspect falling back to '1:1', a non-headless branch returning artifact_html, and an error shape of {error, failure_kind}. The readOnlyHint is consistent — it renders artifacts without mutating stored data — so there is no contradiction.

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?

Purpose and prerequisite are front-loaded, and the Story format / Args / Returns sections are scannable. It is long, and a few lines (the 'Never invent image URLs' and 'Never write placeholder text' admonitions, the trailing 'and more' on chart types) sit outside the core contract, but nearly every sentence carries operational information the agent would otherwise get wrong.

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 a nested untyped payload, an output schema and a required companion call, the description covers everything material: authoring prerequisites, the story contract, parameter overrides, both return branches, the render_url fallback for environments where images are invisible, and error handling. Restating the return shape is slightly redundant against the output schema but useful given the dual-render paths.

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

Parameters5/5

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

Schema description coverage is 0%, so the description must carry the burden and does: it enumerates all seven parameters, marks visual_story_content as requiring a non-empty cards list, frames company/period/industry/palette/language as optional overrides of the story's own fields, and lists the exact aspect values with the fallback behaviour. It also sketches the nested story shape (palette names, cards 4-7, first = cover, field limits) that the untyped object schema cannot express.

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?

Opens with a specific verb pair and resource: 'Validate and render a VisualStoryContent v2 story that you authored into PNG cards', and immediately clarifies 'No LLM call' so the agent knows it supplies the content. It is clearly distinguished from the sibling get_visual_cards_guide, which is named as the prerequisite step rather than the renderer.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit precondition with an exception: call get_visual_cards_guide ONCE before authoring, skip only when re-rendering a story just authored with it. It also states the failure consequence (wrong templateId, no mode, no cover card) and prescribes a retry loop when render_qa is present, which is exactly the when/when-not guidance an agent needs.

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

All Clarifo tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.