Skip to main content
Glama

create_document

Creates a rich document. contentMarkdown (optional) — GFM Markdown — is the RECOMMENDED PATH to set an initial content, in preference to content (raw ProseMirror tree, reserved for cases that build it programmatically). Both omitted: the document is born empty, to be filled by a later update_document. cellId (optional) immediately attaches the document to a canvas block; omitted, it is born detached. warnings (ABSENT when nothing is altered) names what the conversion could not carry (code block info after the language, hard break in a heading). REFUSED with their reason: raw HTML, checkboxes, nesting beyond 100 levels; a literal angle bracket outside code is written \<x> or between backticks. A request blocked by the network firewall (a bare HTTP 403 "Forbidden") answers before the application runs, so it carries NO application message; a document body that is read as an attack pattern (for instance a path traversal such as ../../, or a URL whose host is an IPv4 address) can trigger it. The response carries url: the DIRECT LINK of the document (opens the project on this document), which the human follows with one click, unlike the title.

Input Schema

NameRequiredDescriptionDefault
kindNoThe FORM of the document. Omitted: 'richtext' — a rich-text tree, editable by hand in the interface, the unchanged default. 'html' makes `htmlSource` the authoritative source: the document becomes a standalone page, rendered as is. ⚠️ IMMUTABLE: a document does not change form after its creation — update_document does not accept this field: the form is set at creation. ⚠️ An html document has NO version history: the three document-revisions tools refuse it by naming it. Its source is authoritative and is read in full with get_document. A revision history only exists for richtext.
titleYesDocument title (1 to 200 characters).
cellIdNoAttach the document to this block immediately. Omitted: the document is born DETACHED — attach it later with update_document({cellId}).
contentNoProseMirror tree of the initial content — reserved for cases that build the tree programmatically (import, migration). `contentMarkdown` is the recommended path for an agent. Providing both at once is an explicit REFUSAL (ambiguous, so it is not resolved silently). Both omitted: empty document, to be filled afterwards by update_document.
htmlSourceNoREQUIRED if `kind: 'html'`, FORBIDDEN otherwise — both refusals are explicit and named. The COMPLETE, SELF-CONTAINED HTML document: markup + `<style>` + `<script>` inline, in a single string (maximum 250000 characters). Meant for what a richtext document cannot carry — an overview page, an interactive report, a visualization, a calculator. Long documentation belongs in an ordinary richtext document (`contentMarkdown`), which stays editable by hand. ⚠️ RISK, STATED TO THE USER WHEN THEY CLICK "▶ Run the document": the sandbox protects the user's SESSION (opaque origin, no cookie or storage) but does NOT guarantee that the document's content stays inside OrgGen — the WebRTC channel is not closed (measured in a browser): anything a document embeds can leave OrgGen. ⚠️ SELF-CONTAINED IN THE STRICT SENSE: the document is served in a sandbox WITHOUT ordinary network access (`fetch`, WebSocket, remote resource). Any REMOTE or RELATIVE resource (`<script src>`, `<link rel=stylesheet>`, `<img src="/x.png">`, a Google font, a CSS `@import`) is REFUSED AT WRITE TIME, naming the offending URL — rather than accepting a document half of which would die silently at display time. Images are embedded as `data:`, CSS and JS are written inline. ⚠️ TWO MANDATORY LINES, whose omission raises NO error — it just yields a document that will look broken. (a) `body` EXPLICITLY declares `background` AND `color`: the document is served in an ISOLATED frame, it inherits nothing from the application theme, so without a declared background it displays in WHITE in the middle of a dark panel. The viewer sets `color-scheme` and `data-og-theme` on `<html>`, but `color-scheme` is a hint to the rendering engine, NOT a stylesheet — it invents no color. (b) a `<meta name="viewport" content="width=device-width, initial-scale=1">`, and content that fits in ~390 px: the panel is readable on a phone. The viewer injects this `<meta>` if it is missing, but this safety net designs nothing — a grid in fixed widths will stay off-screen. ⚠️ NINE COMMON CONSTRUCTIONS ARE DEAD in this sandbox, WITHOUT any error being reported (the write succeeds, the document displays, the button stays inert) — including `alert()`, `window.print()`, `localStorage`, forms, `eval`, and `confirm()`, which returns `false` in every case: the "cancel" branch runs, it is the only one whose result is WRONG instead of inert. The nine, with what works instead, are listed in `get_playbook({topic: "html"})`.
visibilityNo'private' creates the document invisible to EVERYONE EXCEPT ITS CREATOR, from this very call — otherwise it is created 'inherited' (visible to whoever has access to the project/block) and making it private requires a second call (update_document({visibility})), with a window where the content is visible in between. Omitted: 'inherited', unchanged behavior.
contentLocaleNoLanguage of the content (fr/en/de/es).
contentMarkdownNoInitial content as Markdown (GFM) — RECOMMENDED PATH. Headings (#), paragraphs, bulleted/numbered lists, tables (| A | B |), quotes (>), code blocks (```), bold/italic/strikethrough/inline code, links ([text](url)), images (![alt](url)), horizontal rules (---). Converted server-side into a ProseMirror tree. An unsupported construct (raw HTML, YAML frontmatter, or a TASK list `- [ ]`/`- [x]` — there is no place for the checkbox) is REFUSED with the offending node type named — it is not silently omitted from the document. A checklist is written as an ordinary list (`- `).
expectedProjectIdNoUUID of the project targeted by THIS call. ACTUALLY targets this project instead of the session project. Refused without changing anything if access is not granted.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed9 schema fields changed
    • changedInput schema / properties / cellId / description
      Previous value: -"Ancrer immédiatement le document à ce bloc. Omis : le document naît DÉTACHÉ — ancre-le plus tard avec update_document({cellId})."New value: +"Attach the document to this block immediately. Omitted: the document is born DETACHED — attach it later with update_document({cellId})."
    • changedInput schema / properties / content / description
      Previous value: -"Arbre ProseMirror du contenu initial — réservé aux cas qui construisent l’arbre programmatiquement (import, migration). `contentMarkdown` est le chemin recommandé pour un agent. Fournir les deux à la fois est un REFUS explicite (ambigu, jamais résolu en silence). Omis les deux : document vide, à remplir ensuite par update_document."New value: +"ProseMirror tree of the initial content — reserved for cases that build the tree programmatically (import, migration). `contentMarkdown` is the recommended path for an agent. Providing both at once is an explicit REFUSAL (ambiguous, so it is not resolved silently). Both omitted: empty document, to be filled afterwards by update_document."
    • changedInput schema / properties / contentLocale / description
      Previous value: -"Langue du contenu (fr/en/de/es)."New value: +"Language of the content (fr/en/de/es)."
    • changedInput schema / properties / contentMarkdown / description
      Previous value: -"Contenu initial en Markdown (GFM) — CHEMIN RECOMMANDÉ. Titres (#), paragraphes, listes à puces/numérotées, tableaux (| A | B |), citations (>), blocs de code (```), gras/italique/barré/code en ligne, liens ([texte](url)), images (![alt](url)), règles horizontales (---). Converti côté serveur en arbre ProseMirror. Un construit non supporté (HTML brut, frontmatter YAML, ou une liste de TÂCHES `- [ ]`/`- [x]` — aucun logement pour la case à cocher) est REFUSÉ avec le type de nœud fautif nommé — jamais silencieusement omis du document. Une check-list s’écrit comme une liste ordinaire (`- `)."New value: +"Initial content as Markdown (GFM) — RECOMMENDED PATH. Headings (#), paragraphs, bulleted/numbered lists, tables (| A | B |), quotes (>), code blocks (```), bold/italic/strikethrough/inline code, links ([text](url)), images (![alt](url)), horizontal rules (---). Converted server-side into a ProseMirror tree. An unsupported construct (raw HTML, YAML frontmatter, or a TASK list `- [ ]`/`- [x]` — there is no place for the checkbox) is REFUSED with the offending node type named — it is not silently omitted from the document. A checklist is written as an ordinary list (`- `)."
    • changedInput schema / properties / expectedProjectId / description
      Previous value: -"UUID du projet visé par CET appel. Cible RÉELLEMENT ce projet au lieu du projet de session. Refusé sans rien modifier si l'accès n'est pas accordé."New value: +"UUID of the project targeted by THIS call. ACTUALLY targets this project instead of the session project. Refused without changing anything if access is not granted."
    • changedInput schema / properties / htmlSource / description
      Previous value: -"REQUIS si `kind: 'html'`, INTERDIT sinon — les deux refus sont explicites et nommés. Le document HTML COMPLET et AUTO-CONTENU : balisage + `<style>` + `<script>` inline, dans une seule chaîne (maximum 250000 caractères). Sert à ce qu’un document richtext ne peut pas porter — tableau de bord, rapport interactif, visualisation, calculateur. La documentation longue relève d’un document richtext ordinaire (`contentMarkdown`), qui reste éditable à la main.\n⚠️ RISQUE, DIT À L’UTILISATEUR AU CLIC « Exécuter » : le bac à sable protège sa SESSION (origine opaque, ni cookie ni stockage) mais ne garantit PAS que le contenu du document reste dans OrgGen — le canal WebRTC n’est pas fermé (mesuré en navigateur) : tout ce qu’un document embarque peut quitter OrgGen.\n⚠️ AUTO-CONTENU AU SENS STRICT : le document est servi dans un bac à sable SANS accès réseau ordinaire (`fetch`, WebSocket, ressource distante). Toute ressource DISTANTE ou RELATIVE (`<script src>`, `<link rel=stylesheet>`, `<img src=\"/x.png\">`, une police Google, un `@import` CSS) est REFUSÉE À L’ÉCRITURE, en nommant l’URL fautive — plutôt que d’accepter un document dont la moitié mourrait en silence à l’affichage. Les images s’embarquent en `data:`, le CSS et le JS s’écrivent en ligne.\n⚠️ DEUX LIGNES OBLIGATOIRES, dont l’oubli ne lève AUCUNE erreur — il rend juste un document qu’on croira cassé. (a) `body` déclare EXPLICITEMENT `background` ET `color` : le document est servi dans un cadre ISOLÉ, il n’hérite rien du thème de l’application, donc sans fond déclaré il s’affiche en BLANC au milieu d’un panneau sombre. La visionneuse définit `color-scheme` et `data-og-theme` sur `<html>`, mais `color-scheme` est un indice au moteur de rendu, PAS une feuille de style — il n’invente aucune couleur. (b) un `<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">`, et un contenu qui tient à ~390 px : le panneau est lisible sur téléphone. La visionneuse injecte ce `<meta>` s’il manque, mais ce filet ne conçoit aucun design — une grille en largeurs fixes restera hors écran.\n⚠️ NEUF CONSTRUCTIONS COURANTES SONT MORTES dans ce bac à sable, SANS qu’aucune erreur ne soit signalée (l’écriture réussit, le document s’affiche, le bouton reste inerte) — dont `alert()`, `window.print()`, `localStorage`, les formulaires, `eval`, et `confirm()` qui rend TOUJOURS `false` : la branche « annuler » s’exécute, c’est la seule dont le résultat est FAUX au lieu d’inerte. Les neuf, avec ce qui marche à la place, sont listées dans `get_playbook({topic: \"html\"})`."New value: +"REQUIRED if `kind: 'html'`, FORBIDDEN otherwise — both refusals are explicit and named. The COMPLETE, SELF-CONTAINED HTML document: markup + `<style>` + `<script>` inline, in a single string (maximum 250000 characters). Meant for what a richtext document cannot carry — an overview page, an interactive report, a visualization, a calculator. Long documentation belongs in an ordinary richtext document (`contentMarkdown`), which stays editable by hand.\n⚠️ RISK, STATED TO THE USER WHEN THEY CLICK \"▶ Run the document\": the sandbox protects the user's SESSION (opaque origin, no cookie or storage) but does NOT guarantee that the document's content stays inside OrgGen — the WebRTC channel is not closed (measured in a browser): anything a document embeds can leave OrgGen.\n⚠️ SELF-CONTAINED IN THE STRICT SENSE: the document is served in a sandbox WITHOUT ordinary network access (`fetch`, WebSocket, remote resource). Any REMOTE or RELATIVE resource (`<script src>`, `<link rel=stylesheet>`, `<img src=\"/x.png\">`, a Google font, a CSS `@import`) is REFUSED AT WRITE TIME, naming the offending URL — rather than accepting a document half of which would die silently at display time. Images are embedded as `data:`, CSS and JS are written inline.\n⚠️ TWO MANDATORY LINES, whose omission raises NO error — it just yields a document that will look broken. (a) `body` EXPLICITLY declares `background` AND `color`: the document is served in an ISOLATED frame, it inherits nothing from the application theme, so without a declared background it displays in WHITE in the middle of a dark panel. The viewer sets `color-scheme` and `data-og-theme` on `<html>`, but `color-scheme` is a hint to the rendering engine, NOT a stylesheet — it invents no color. (b) a `<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">`, and content that fits in ~390 px: the panel is readable on a phone. The viewer injects this `<meta>` if it is missing, but this safety net designs nothing — a grid in fixed widths will stay off-screen.\n⚠️ NINE COMMON CONSTRUCTIONS ARE DEAD in this sandbox, WITHOUT any error being reported (the write succeeds, the document displays, the button stays inert) — including `alert()`, `window.print()`, `localStorage`, forms, `eval`, and `confirm()`, which returns `false` in every case: the \"cancel\" branch runs, it is the only one whose result is WRONG instead of inert. The nine, with what works instead, are listed in `get_playbook({topic: \"html\"})`."
    • changedInput schema / properties / kind / description
      Previous value: -"La FORME du document. Omis : 'richtext' — un arbre de texte riche, éditable à la main dans l'interface, le défaut inchangé. 'html' fait de `htmlSource` la source d’autorité : le document devient une page autonome, rendue telle quelle. ⚠️ IMMUABLE : un document ne change JAMAIS de forme après sa création — update_document n’accepte pas ce champ : la forme se fixe à la création.\n⚠️ Un document html n’a PAS d’historique de versions : les trois outils document-revisions le refusent en le nommant. Sa source fait autorité et se relit en entier avec get_document. Un historique de révisions n’existe que pour richtext."New value: +"The FORM of the document. Omitted: 'richtext' — a rich-text tree, editable by hand in the interface, the unchanged default. 'html' makes `htmlSource` the authoritative source: the document becomes a standalone page, rendered as is. ⚠️ IMMUTABLE: a document does not change form after its creation — update_document does not accept this field: the form is set at creation.\n⚠️ An html document has NO version history: the three document-revisions tools refuse it by naming it. Its source is authoritative and is read in full with get_document. A revision history only exists for richtext."
    • changedInput schema / properties / title / description
      Previous value: -"Titre du document (1 à 200 caractères)."New value: +"Document title (1 to 200 characters)."
    • changedInput schema / properties / visibility / description
      Previous value: -"'private' fait naître le document invisible à TOUT LE MONDE SAUF SON CRÉATEUR, dès cet appel — sans quoi il naît 'inherited' (visible à qui a accès au projet/bloc) et le rendre privé exige un second appel (update_document({visibility})), avec une fenêtre où le contenu est visible entre les deux. Omis : 'inherited', comportement inchangé."New value: +"'private' creates the document invisible to EVERYONE EXCEPT ITS CREATOR, from this very call — otherwise it is created 'inherited' (visible to whoever has access to the project/block) and making it private requires a second call (update_document({visibility})), with a window where the content is visible in between. Omitted: 'inherited', unchanged behavior."
  2. Changed4 schema fields changed
    • changedInput schema / properties / content / description
      Previous value: -"Arbre ProseMirror du contenu initial — réservé aux cas qui construisent l’arbre programmatiquement (import, migration). PRÉFÈRE `contentMarkdown` : c’est le chemin recommandé pour un agent. Fournir les deux à la fois est un REFUS explicite (ambigu, jamais résolu en silence). Omis les deux : document vide, à remplir ensuite par update_document."New value: +"Arbre ProseMirror du contenu initial — réservé aux cas qui construisent l’arbre programmatiquement (import, migration). `contentMarkdown` est le chemin recommandé pour un agent. Fournir les deux à la fois est un REFUS explicite (ambigu, jamais résolu en silence). Omis les deux : document vide, à remplir ensuite par update_document."
    • changedInput schema / properties / contentMarkdown / description
      Previous value: -"Contenu initial en Markdown (GFM) — CHEMIN RECOMMANDÉ. Titres (#), paragraphes, listes à puces/numérotées, tableaux (| A | B |), citations (>), blocs de code (```), gras/italique/barré/code en ligne, liens ([texte](url)), images (![alt](url)), règles horizontales (---). Converti côté serveur en arbre ProseMirror. Un construit non supporté (HTML brut, frontmatter YAML, ou une liste de TÂCHES `- [ ]`/`- [x]` — aucun logement pour la case à cocher) est REFUSÉ avec le type de nœud fautif nommé — jamais silencieusement omis du document. Écris une liste ordinaire (`- `) si tu veux une check-list."New value: +"Contenu initial en Markdown (GFM) — CHEMIN RECOMMANDÉ. Titres (#), paragraphes, listes à puces/numérotées, tableaux (| A | B |), citations (>), blocs de code (```), gras/italique/barré/code en ligne, liens ([texte](url)), images (![alt](url)), règles horizontales (---). Converti côté serveur en arbre ProseMirror. Un construit non supporté (HTML brut, frontmatter YAML, ou une liste de TÂCHES `- [ ]`/`- [x]` — aucun logement pour la case à cocher) est REFUSÉ avec le type de nœud fautif nommé — jamais silencieusement omis du document. Une check-list s’écrit comme une liste ordinaire (`- `)."
    • changedInput schema / properties / htmlSource / description
      Previous value: -"REQUIS si `kind: 'html'`, INTERDIT sinon — les deux refus sont explicites et nommés. Le document HTML COMPLET et AUTO-CONTENU : balisage + `<style>` + `<script>` inline, dans une seule chaîne (maximum 250000 caractères). Sert à ce qu’un document richtext ne peut pas porter — tableau de bord, rapport interactif, visualisation, calculateur. Pour de la documentation longue, garde un document richtext ordinaire (`contentMarkdown`), qui reste éditable à la main.\n⚠️ RISQUE, DIT À L’UTILISATEUR AU CLIC « Exécuter » : le bac à sable protège sa SESSION (origine opaque, ni cookie ni stockage) mais ne garantit PAS que le contenu du document reste dans OrgGen — le canal WebRTC n’est pas fermé (mesuré en navigateur). N’embarque dans un document que ce qui peut quitter OrgGen.\n⚠️ AUTO-CONTENU AU SENS STRICT : le document est servi dans un bac à sable SANS accès réseau ordinaire (`fetch`, WebSocket, ressource distante). Toute ressource DISTANTE ou RELATIVE (`<script src>`, `<link rel=stylesheet>`, `<img src=\"/x.png\">`, une police Google, un `@import` CSS) est REFUSÉE À L’ÉCRITURE, en nommant l’URL fautive — plutôt que d’accepter un document dont la moitié mourrait en silence à l’affichage. Embarque tes images en `data:` et écris ton CSS/JS en ligne.\n⚠️ DEUX LIGNES OBLIGATOIRES, dont l’oubli ne lève AUCUNE erreur — il rend juste un document qu’on croira cassé. (a) `body` déclare EXPLICITEMENT `background` ET `color` : le document est servi dans un cadre ISOLÉ, il n’hérite rien du thème de l’application, donc sans fond déclaré il s’affiche en BLANC au milieu d’un panneau sombre. La visionneuse pose `color-scheme` et `data-og-theme` sur `<html>`, mais `color-scheme` est un indice au moteur de rendu, PAS une feuille de style — il n’invente aucune couleur. (b) un `<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">`, et un contenu qui tient à ~390 px : le panneau est lisible sur téléphone. La visionneuse injecte ce `<meta>` s’il manque, mais ce filet ne devine pas un design — une grille en largeurs fixes restera hors écran.\n⚠️ NEUF CONSTRUCTS COURANTS NE MARCHENT PAS dans ce bac à sable — dont `alert()`, `window.print()`, `localStorage`, les formulaires, `eval`, et `confirm()` qui rend TOUJOURS `false` (donc la branche « annuler » s’exécute). Appelle `get_playbook({topic: \"html\"})` AVANT d’écrire : la liste complète y est, avec ce qui marche à la place."New value: +"REQUIS si `kind: 'html'`, INTERDIT sinon — les deux refus sont explicites et nommés. Le document HTML COMPLET et AUTO-CONTENU : balisage + `<style>` + `<script>` inline, dans une seule chaîne (maximum 250000 caractères). Sert à ce qu’un document richtext ne peut pas porter — tableau de bord, rapport interactif, visualisation, calculateur. La documentation longue relève d’un document richtext ordinaire (`contentMarkdown`), qui reste éditable à la main.\n⚠️ RISQUE, DIT À L’UTILISATEUR AU CLIC « Exécuter » : le bac à sable protège sa SESSION (origine opaque, ni cookie ni stockage) mais ne garantit PAS que le contenu du document reste dans OrgGen — le canal WebRTC n’est pas fermé (mesuré en navigateur) : tout ce qu’un document embarque peut quitter OrgGen.\n⚠️ AUTO-CONTENU AU SENS STRICT : le document est servi dans un bac à sable SANS accès réseau ordinaire (`fetch`, WebSocket, ressource distante). Toute ressource DISTANTE ou RELATIVE (`<script src>`, `<link rel=stylesheet>`, `<img src=\"/x.png\">`, une police Google, un `@import` CSS) est REFUSÉE À L’ÉCRITURE, en nommant l’URL fautive — plutôt que d’accepter un document dont la moitié mourrait en silence à l’affichage. Les images s’embarquent en `data:`, le CSS et le JS s’écrivent en ligne.\n⚠️ DEUX LIGNES OBLIGATOIRES, dont l’oubli ne lève AUCUNE erreur — il rend juste un document qu’on croira cassé. (a) `body` déclare EXPLICITEMENT `background` ET `color` : le document est servi dans un cadre ISOLÉ, il n’hérite rien du thème de l’application, donc sans fond déclaré il s’affiche en BLANC au milieu d’un panneau sombre. La visionneuse définit `color-scheme` et `data-og-theme` sur `<html>`, mais `color-scheme` est un indice au moteur de rendu, PAS une feuille de style — il n’invente aucune couleur. (b) un `<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">`, et un contenu qui tient à ~390 px : le panneau est lisible sur téléphone. La visionneuse injecte ce `<meta>` s’il manque, mais ce filet ne conçoit aucun design — une grille en largeurs fixes restera hors écran.\n⚠️ NEUF CONSTRUCTIONS COURANTES SONT MORTES dans ce bac à sable, SANS qu’aucune erreur ne soit signalée (l’écriture réussit, le document s’affiche, le bouton reste inerte) — dont `alert()`, `window.print()`, `localStorage`, les formulaires, `eval`, et `confirm()` qui rend TOUJOURS `false` : la branche « annuler » s’exécute, c’est la seule dont le résultat est FAUX au lieu d’inerte. Les neuf, avec ce qui marche à la place, sont listées dans `get_playbook({topic: \"html\"})`."
    • changedInput schema / properties / kind / description
      Previous value: -"La FORME du document. Omis : 'richtext' — un arbre de texte riche, éditable à la main dans l'interface, le défaut inchangé. 'html' fait de `htmlSource` la source d’autorité : le document devient une page autonome, rendue telle quelle. ⚠️ IMMUABLE : un document ne change JAMAIS de forme après sa création — update_document n’accepte pas ce champ. Choisis maintenant.\n⚠️ Un document html n’a PAS d’historique de versions : les trois outils document-revisions le refusent en le nommant. Sa source fait autorité et se relit en entier avec get_document. Si l’historique compte, prends richtext."New value: +"La FORME du document. Omis : 'richtext' — un arbre de texte riche, éditable à la main dans l'interface, le défaut inchangé. 'html' fait de `htmlSource` la source d’autorité : le document devient une page autonome, rendue telle quelle. ⚠️ IMMUABLE : un document ne change JAMAIS de forme après sa création — update_document n’accepte pas ce champ : la forme se fixe à la création.\n⚠️ Un document html n’a PAS d’historique de versions : les trois outils document-revisions le refusent en le nommant. Sa source fait autorité et se relit en entier avec get_document. Un historique de révisions n’existe que pour richtext."
  3. First observed

TDQS

A4.4/5.0
Behavior5/5

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

Annotations already mark it as non-read-only, non-destructive, and closed-world, but the description adds substantial behavioral context: refused constructs (raw HTML, checkboxes, deep nesting), the meaning of the warnings field, a firewall 403 behavior that produces no application message, attack-pattern triggers, and the response url field. Nothing contradicts the annotations.

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 description is long and dense, but each sentence carries concrete information and the core purpose is front-loaded. Some tangential details (e.g., firewall 403 and attack-pattern examples) could be trimmed or moved to error documentation, but overall it is efficient and 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 creation tool with no output schema, the description covers response fields (url, warnings), refusal conditions, sandbox behavior, and integration with update_document. It provides enough context for an agent to call the tool correctly and interpret common failure modes.

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%, so the parameter semantics are fully documented in the schema. The description largely repeats that information (e.g., contentMarkdown recommended, both omitted means empty) with minor emphasis, but adds little new parameter-specific meaning beyond what the schema already states.

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 and resource: 'Creates a rich document.' It distinguishes the primary content-creation paths (contentMarkdown vs. content) and clarifies that an empty document can be created for later filling with update_document. The purpose is unambiguous and not a tautology.

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 gives clear conditional guidance: contentMarkdown is the recommended path over content, both omitted yields an empty document, and cellId attaches the document at creation. However, it does not explicitly state when to use this tool versus siblings like add_content_block or update_document beyond a passing mention, so an agent must infer routing from resource names.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.