livediagram

Write an article

write_article

Destructive

Write an article (a document of text on pages, in Pages mode) from Markdown: a new one, or replace or append to one named by id or title, with its look. The editor flows the text onto as many pages as it needs. read_document with view "pages" shows each article as Markdown to edit and write back. Not for slides: an article flows as running text, where a slide deck is slide pages, made with change_pages.

Input Schema

TableJSON Schema

Name	Required	Description
`new`	No	Always start a new article.
`look`	No	The article’s look: clean, classic, report, notebook or bold.
`mode`	No	replace (default) writes the text anew; append adds it after the last block.
`size`	No	A new article’s paper: a4 (default), letter, a3, square, social or wide.
`tabId`	No	The tab. Absent: the first tab in Pages mode. Naming a tab in another mode switches it into Pages.
`accent`	No	The accent colour, a hex.
`article`	No	Which article, by id or title. Absent: the tab’s only one, or a new one if it has none.
`markdown`	Yes	The text, in Markdown: # ## ### headings, paragraphs, - and 1. lists (indent two spaces a level), - [ ] to-dos, > quotes, ``` code, --- dividers, bold, italic, ~~strike~~, `code`, [links](https://…). Front matter sets the title and subtitle: a first line ---, then title: …, subtitle: …, then ---. A line \pagebreak starts a new page; a line [zone <id>] keeps an existing zone there. An article holds no tables: a Markdown table is written as a list.
`documentId`	Yes	The document (from find_documents).
`orientation`	No	Portrait or landscape. Slides and logo pages have none.
`pageNumbers`	No	Page numbers in the bottom margin on or off.

Output Schema

TableJSON Schema

Name	Required	Description
`rev`	Yes	The tab revision written.
`url`	Yes	Link that opens the document in the livediagram editor.
`lines`	Yes	What was done, one line each.
`pages`	Yes	Every page of the tab as it now is.
`tabId`	Yes	The tab changed.
`article`	Yes	The article written.
`articles`	Yes	Every article of the tab.
`switched`	Yes	Whether the tab was switched into Pages mode.
`documentId`	Yes	The document id.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 18, 2026

changedInput schema / properties / tabId / description

Previous value: -"The tab. Absent: the first tab in Illustrate mode. Naming a tab in another mode switches it into Illustrate."New value: +"The tab. Absent: the first tab in Pages mode. Naming a tab in another mode switches it into Pages."

changedOutput schema / properties / switched / description

Previous value: -"Whether the tab was switched into Illustrate mode."New value: +"Whether the tab was switched into Pages mode."

Changed2 schema fields changedOct 14, 2026

addedOutput schema / properties / article / properties / estimatedPages

Added value: +{
+  "description": "About how many pages its writing reaches once laid out (an estimate): the editor grows the article to them, so more than its pages means it runs on.",
+  "type": "number"
+}

addedOutput schema / properties / articles / items / properties / estimatedPages

Added value: +{
+  "description": "About how many pages its writing reaches once laid out (an estimate): the editor grows the article to them, so more than its pages means it runs on.",
+  "type": "number"
+}

AddedOct 10, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds the meaningful distinction that the call can either overwrite ('replace... writes the text anew' per schema) or append to an existing article by id or title, plus the fact that the editor paginates automatically. It does not spell out the loss of pre-existing content on a replace or any permission/rate constraints, which keeps it short of a 5.

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 with the verb and resource, and the critical exclusion ('Not for slides') lands before the closing clause. Dense but each sentence adds routing or behavioral value; only the pagination aside is arguably optional.

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 destructive 11-parameter write tool with an output schema (so return values need not be explained), the description covers creation vs. replacement, target selection, the read-back workflow, and the sibling that handles the slide case. Nothing an agent needs to call it correctly is 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 description coverage is 100% across all 11 parameters, so the schema already carries the enum values, defaults and Markdown syntax notes; the description only gestures at 'named by id or title' and 'with its look.' Baseline 3 is appropriate when structured fields do the parameter work.

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?

Specific verb (write) plus resource (an article: text on pages in Pages mode) and a stated source format (Markdown). It also explicitly demarcates scope against siblings: 'Not for slides... made with change_pages,' so an agent can route without opening any schema.

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?

States when to use it, names the excluded case and the sibling that handles it (slides → change_pages), and gives the companion read path (read_document with view "pages") for editing round-trips. Nothing is left to inference.

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

All livediagram tools Inspect

Try in Browser

Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?