Clarifo

preview_document_update

Read-onlyIdempotent

Show how one part of a Clarifo document would change, or what publishing it would do. Writes nothing. Use when the user asks to change, rewrite, update or add to an existing document. Give exactly one target:

section_id + markdown: a section (get_workspace_item view="manifest").
block_id + markdown: one paragraph, list or table (view="blocks"); a table as a Markdown table.
visual_id + visual_data: the data of one saved chart, map or heatmap (view="visuals"; visual_data is its saved_data as read, or just the data object inside it (chartData, ...); every stored key kept). The result shows Clarifo's rendering of the saved and the proposed chart.
visual_story: the whole Visual Story (as view="visuals" returns it, changed). The result shows the proposed cards.
seo: publishing settings {"title", "description", "slug", "cover_image_url", "cover_image_alt"}; keys left out stay; cover_image_url "" removes the cover. The address (slug) is fixed once the document has been published.
publish: "public" (on clarifo.com for anyone) or "private" (signed-in Clarifo users only), only when the user asks to publish. The result shows the document as it would be published, its title, address, visibility, last check and whether the plan allows it.

Show the user the diff and the images (for publish: the preview, the address and visibility), then call apply_document_update with the same arguments plus base_version and preview_hash only after they agree.

Args: item_id: The document, from list_workspace_items. section_id: The section to change (manifest), or "intro". markdown: The new text, for a section or block. For a section replace without a leading heading the section keeps its heading; for insert_after start with a ## heading. Cite a filing page as [page_id] and list it in sources. None for remove. operation: replace (default), insert_after, or remove (takes the section, with its subsections, or the block out; no markdown). A part holding a chart is not removed here. sources: Filing page_ids the new text or cards rest on. Omitted for a section or block: the pages it already cites (sources_inherited in the result). companies: Optional; not used (figures are not checked). workspace_id: Optional; the document's workspace. block_id: One block to replace or insert after (view="blocks"). visual_id: A saved chart's V (view="visuals"). visual_data: The chart's new data, with visual_id. visual_story: The new Visual Story. seo: New publishing settings (SEO title, description, URL slug, cover image). publish: "public" or "private" to preview publishing the document; give no other target with it.

Returns: {"section" | "block_id" | "visual", "old_text", "new_text", "diff", "base_version", "preview_hash"} (+ images for a visual) or {"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": {
      "item_id": "<item_id>"
    },
    "name": "preview_document_update"
  }
}

Input Schema

Name	Required	Default
`seo`	No
`item_id`	Yes
`publish`	No
`sources`	No
`block_id`	No
`markdown`	No
`companies`	No
`operation`	No	replace
`visual_id`	No
`section_id`	No
`visual_data`	No
`visual_story`	No
`workspace_id`	No

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 readOnlyHint/idempotentHint=true, and the description reinforces this with 'Writes nothing' plus concrete behavioral facts beyond the annotations: the slug is fixed once published, publish is allowed only when the user asks, omitted sources inherit existing citations, and omitted SEO keys are preserved while empty cover_image_url removes the cover.

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?

Front-loaded purpose followed by a scannable target list, then a workflow instruction, then an Args block. It is long and partly redundant — the markdown/visual_id/seo/publish semantics appear both in the target bullets and again in Args — but every section remains navigable and nothing is padding.

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 13-parameter preview tool with branching target modes, the definition covers all modes, the handoff to apply_document_update, and return shape (even though an output schema exists). An agent has everything needed to pick a target and construct a valid call.

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% across 13 parameters, so the description carries the full burden and does so: operation's three values are explained with their effects, markdown formatting rules for replace vs insert_after vs remove are spelled out, sources inheritance is described, companies is flagged as unused, and publish's two allowed values are defined.

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 and resource: 'Show how one part of a Clarifo document would change, or what publishing it would do. Writes nothing.' It immediately distinguishes itself from the mutating sibling apply_document_update, which is named later in the text.

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 trigger ('Use when the user asks to change, rewrite, update or add to an existing document'), enumerates the mutually exclusive target combinations, and states the workflow boundary: only call apply_document_update with the same arguments plus base_version and preview_hash after the user agrees.

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.