Collaborative word processor you can use with your agent.
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Average 4.4/5 across 18 of 18 tools scored. Lowest: 2.9/5.
Each tool targets a distinct action or resource: creation tools differ by input source (inline markdown, public URL, local file), reading tools by granularity (full read, outline, search, info, changes), and editing tools by scope (targeted edits, full replace, footnote insertion, styling, layout). No two tools have overlapping purposes.
All tools follow a consistent snake_case verb_noun pattern (e.g., create_document, read_document, export_document). Even compound operations like set_page_layout and search_within_document maintain the predictable verb-first structure.
At 18 tools, the set is slightly above the ideal 3-15 range, but each tool addresses a distinct document workflow need (creation, reading, editing, collaboration, export, cleanup). The density is justified by the comprehensive feature set, though a few could be consolidated.
The surface covers document lifecycle well (create, read, edit, export, clean) but lacks a delete_document tool and targeted comment management (only leave comments, no resolve/delete comment). Selective handling of others' tracked changes is also missing, with clean_document being the only way to resolve all suggestions destructively.
clean_documentClean document metadataAScrub a document before it is shared externally ("clean this document before I send it"): remove comments, resolve ALL pending tracked-change suggestions (accept or reject — everyone's, not just yours), remove hidden text (Word w:vanish), anonymize revision/comment author names to "Author", and clear document properties (title/author/company metadata from the original file). Destructive and not undoable — confirm with the user before running it. Options all default to off; enable only what the user asked to strip. Returns a summary of what was removed.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Document ID | |
| remove_comments | No | Remove all comment threads and their anchors | |
| anonymize_authors | No | Replace suggestion and comment author identities with "Author" | |
| remove_hidden_text | No | Remove hidden (invisible-in-Word) text spans; footnote/endnote numerals are kept | |
| resolve_suggestions | No | Resolve ALL pending suggestions: accept applies them, reject reverts them; omit to leave them pending | |
| clear_core_properties | No | Wipe document properties (author, title, company, created/modified dates) |
| Name | Required | Description |
|---|---|---|
| status | Yes | Scrub outcome |
| hiddenRemoved | Yes | Hidden text spans removed (note-reference numerals are kept) |
| commentsRemoved | Yes | Distinct comment threads removed |
| corePropsCleared | Yes | Whether document properties (docProps/core.xml) were wiped |
| authorsAnonymized | Yes | Distinct author identities replaced with "Author" |
| suggestionsResolved | Yes | Distinct pending suggestions resolved |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description adds crucial behavioral specifics: 'not undoable', 'Options all default to off; enable only what the user asked to strip', 'resolve ALL pending tracked-change suggestions (accept or reject — everyone's, not just yours)', and 'Returns a summary of what was removed'. These details inform the agent about default behavior, scope, and output in a way the annotations alone do not.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two main sentences plus a short final sentence. It is dense with information but well-organized as a list of actions, a warning, a default-behavior note, and an output summary. While slightly long, each clause contributes value, making it efficient for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given six parameters, a destructive nature, and an output schema, the description covers all critical aspects: purpose, exact actions, parameter defaults, safety, and return value. The output schema is mentioned ('Returns a summary of what was removed') without duplicating its structure. This is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, providing descriptions for every parameter. The description adds meaning by clarifying defaults ('Options all default to off') and amplifying scope ('everyone's, not just yours' for suggestions, 'Word w:vanish' for hidden text). These additions go beyond the schema's baseline, earning a 4 rather than a flat 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific, user-directed verb phrase 'Scrub a document before it is shared externally' and enumerates exact actions (remove comments, resolve suggestions, remove hidden text, anonymize authors, clear properties). This clearly distinguishes it from tools like resolve_suggestions or edit_document, which handle individual aspects rather than the full cleaning workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context for when to use the tool ('before it is shared externally') and includes a direct user quote ('clean this document before I send it'). It also gives a safety directive: 'confirm with the user before running it.' However, it does not explicitly name alternative tools (e.g., resolve_suggestions) for narrower tasks, leaving the choice to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_documentCreate document (no account)AInspectCreate a Revise document without a Revise account, seeded with markdown. Returns: url (give this to your user — they open it to view the document and create a free account to keep it, in one step) and edit_token (keep it; use it as your Authorization Bearer token in future requests to read and edit this document). The document is private and deleted after 7 days if unclaimed.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Document title | |
| created_by | No | Your name (e.g. "Codex", "Claude") so the user sees who made the document. Recommended. | |
| content_markdown | No | Initial content as markdown |
| Name | Required | Description |
|---|---|---|
| id | Yes | Document ID |
| url | Yes | Editor URL |
| notes | Yes | Human-facing claim and retention notes |
| title | Yes | Document title |
| edit_token | Yes | Bearer token scoped to this document for future read/edit calls |
| unlock_more | Yes | Agent-facing guidance for authenticating to unlock more tools |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (which are all false), the description reveals critical behaviors: the document is private, deleted after 7 days if unclaimed, and the returned edit_token serves as an authorization bearer for future requests. This adds substantial value for agent decision-making.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: four sentences front-load the purpose, then detail return values and lifecycle. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of an output schema (not shown but present), the description still explains return values and lifecycle, making it complete. It covers all relevant aspects for a creation tool: input, output, side effects, and token usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with adequate parameter descriptions. The tool description does not add significant extra meaning beyond the schema; it only contextualizes the overall workflow. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a Revise document without an account, seeded with markdown. It distinguishes from sibling tools like edit_document and import_document by focusing on account-free creation and the specific workflow of returning a URL and edit_token.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly tells when to use this tool (when no account exists) but does not explicitly differentiate from alternatives like a hypothetical 'create_document_with_account'. It provides clear context about the result and subsequent use of the edit_token, but lacks explicit when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
edit_documentEdit documentAApply targeted edits to a document using Markdown or HTML content. Edits land as pending tracked changes ("suggest" mode) that the owner reviews and accepts or rejects in the editor — this is the default and the right choice unless your user explicitly asks for direct edits. Pass mode "apply" only on explicit instruction (e.g. "apply it directly", "don't leave suggestions"); it writes immediately with no review step, recorded in the revision history. One exception needs no instruction: on a short/new document (under 20 words) the default is already "apply", since there is nothing meaningful to review. Get block ids from read_document with with_block_ids: true.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Document ID | |
| mode | No | Omit for the default: suggest (tracked changes) on documents with 20+ words, apply on shorter ones. Choose "apply" on a substantial document only when your user explicitly asked for direct edits without review — never on your own judgment. | |
| edits | Yes | Edits to perform, in order |
| Name | Required | Description |
|---|---|---|
| note | No | Review guidance |
| status | Yes | Whether edits were suggested or directly applied |
| editsRequested | No | Requested edit count |
| pendingSuggestionIds | No | Tracked-change suggestion IDs |
| acceptedChangeRegions | No | Change regions accepted immediately |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, so the description adds value by explaining the tracked changes behavior (pending review) and the immediate write in 'apply' mode, with exception for short documents. It discloses the default mode and the need for explicit instruction for direct edits, but could mention more about side effects or errors. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences front-loaded with purpose, then mode guidance, then the exception. Every sentence adds necessary information without redundancy. Highly efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (3 parameters, one a complex array) and the presence of an output schema, the description is complete enough: it covers core behavior, mode choices, and block_id sourcing. It doesn't explain error handling or return values but the output schema covers that. Slight gap in not mentioning what happens if find fails, but overall substantial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for each parameter, so baseline is 3. The description adds significant value by explaining the mode default logic (suggest vs apply, short document exception) and how to source block_ids from read_document, enhancing the schema's static descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool applies targeted edits to a document using Markdown or HTML. It specifies the resource (document) and action (edits via tracked changes or direct apply), and the title 'Edit document' aligns well. It distinguishes from siblings like create_document, read_document, or replace_document_content by detailing the editing mode and block-level operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance on when to use each mode: default 'suggest' (tracked changes) unless user explicitly asks for 'apply', with a special case for short/new documents (<20 words) where 'apply' is default. It also instructs to get block ids from read_document with with_block_ids:true, providing clear when and how to use the tool relative to others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
export_documentExport documentAExport a document by id to markdown, txt, html, docx, pdf. Markdown is returned inline. Every other format (txt, html, docx, pdf) is hosted at a temporary download URL (expires in ~24h) returned in the response, not streamed back inline.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Document ID | |
| format | Yes |
| Name | Required | Description |
|---|---|---|
| id | Yes | Document ID |
| bytes | No | Hosted file byte length |
| notes | No | Download expiry notes |
| format | Yes | Export format |
| status | Yes | Export status |
| content | No | Inline exported text content |
| download_url | No | Temporary download URL |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behavioral traits beyond annotations: markdown inline vs other formats via temporary URL with 24h expiry. Annotations indicate readOnlyHint=true, which aligns with the description of a non-destructive export operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the primary action and then detail. Every sentence adds value; no repetition of schema or annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only 2 parameters and an output schema, the description fully covers the key aspects: supported formats, inline vs URL returns, and expiry. No additional context needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaning beyond the schema: explains how the 'format' parameter affects output delivery. The schema only lists enums; the description clarifies the behavioral difference for markdown vs other formats. The 'id' parameter is straightforward.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action (export a document by id), resource (document), and supported formats (markdown, txt, html, docx, pdf). This specificity distinguishes it from sibling tools like read_document or get_document_info.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context on when to use the tool (exporting documents) and describes format-specific behavior (inline markdown vs temporary URL for others). Lacks explicit 'when not to use' or alternatives, but the sibling list and context are sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_document_infoGet document infoAGet a document's metadata: title, sharing state, URLs, timestamps, and word count.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Document ID |
| Name | Required | Description |
|---|---|---|
| id | Yes | Document ID |
| url | Yes | Editor URL |
| pages | Yes | Rendered page count, or null in pageless mode |
| title | Yes | Document title |
| words | Yes | Word count |
| blocks | Yes | Top-level block count |
| isOwner | Yes | Whether the current user owns the document |
| isPublic | Yes | Whether the document is publicly shared |
| readOnly | Yes | Whether the current user has read-only access |
| createdAt | No | Creation timestamp from the Revise API |
| publicUrl | Yes | Public URL, when enabled |
| updatedAt | No | Last update timestamp from the Revise API |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value by specifying the exact metadata fields returned, which goes beyond the annotation's safety profile. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with purpose, and lists specific metadata fields without any extraneous words. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity and many sibling tools, the description covers the essential information to differentiate. It lists return fields, which is sufficient since an output schema exists. Would benefit from a brief usage note, but still good.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single 'id' parameter described as 'Document ID'. The description does not add additional meaning or format tips beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'document metadata', and lists specific fields (title, sharing state, URLs, timestamps, word count). This distinguishes it from siblings like read_document (full content) and get_document_outline (structure).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (to retrieve metadata), but does not explicitly state when not to use or mention alternative tools. The context is clear but lacks explicit exclusions or comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_document_outlineGet document outlineAGet a document's heading outline with block ids and per-section word counts. Cheap way to orient in a long document before reading specific sections.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Document ID |
| Name | Required | Description |
|---|---|---|
| title | Yes | Document title |
| blocks | Yes | Top-level block count |
| sections | Yes | |
| totalWords | Yes | Total word count |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the tool is safe. The description adds 'cheap' to indicate low cost, but overall adds limited behavioral detail beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with front-loaded purpose and usage guidance. No extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and annotations, the description sufficiently explains what the tool returns (heading outline, block ids, word counts) and its use case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the only parameter 'id' is described in the schema. The description does not add parameter-specific details, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Get a document's heading outline with block ids and per-section word counts.' It uses a specific verb and resource, and distinguishes from siblings like read_document that get full content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description adds 'Cheap way to orient in a long document before reading specific sections,' which effectively tells when to use it. Although it does not explicitly exclude alternatives, the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_recent_changesGet recent changesASee what changed in a document since YOU last looked at it — e.g. edits the human (or another collaborator) made in between. Returns added, removed, and changed blocks (with block ids), all in the accepted/projected state. Great for catching up before continuing work ("how does it look now?"). The first call on a document just establishes a baseline. Each call advances your baseline to the current state.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Document ID |
| Name | Required | Description |
|---|---|---|
| note | No | Result note or truncation guidance |
| added | No | Added blocks |
| since | No | ISO timestamp for the previous baseline |
| changed | No | Changed blocks |
| removed | No | Removed blocks |
| summary | No | Exact changed-block counts |
| baselineEstablished | No | True when this first call only established a baseline |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and destructiveHint, but the description adds rich behavioral detail: returns added/removed/changed blocks with block ids, accepted/projected state, baseline establishment per call. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four focused sentences: first states main purpose, second details output, third gives usage context, fourth explains baseline. No wasted words, front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool (one param, output schema exists, annotations cover safety), the description fully explains behavior, output, and usage. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter 'id' with description 'Document ID' in schema (100% coverage). The description adds no further details about the parameter beyond the schema, but the tool description as a whole provides context. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool shows changes since the user last looked at the document, using a specific verb ('see what changed') and resource ('a document'). It distinguishes from siblings by emphasizing the 'since YOU last looked' aspect and the return of specific block types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: 'Great for catching up before continuing work' and explains baseline behavior. It implicitly guides when to use, though it lacks explicit when-not-to-use statements or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
import_documentImport document (no account)AInspectCreate a Revise document from a file at a public http(s) URL (.md, .markdown, .txt, .html, .htm, .docx, .rtf, .odt; PDFs/images not yet supported). The server fetches the URL — file bytes are never passed inline. For a LOCAL file, use upload_document instead (it streams the file to the server). Returns the new document id and URL. Returns url (give it to your user — they view the document and create a free account to keep it, in one step) and edit_token (your Bearer token for future edits). The document is private and deleted after 7 days if unclaimed.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Public http(s) URL of the file for the server to fetch | |
| title | No | Document title | |
| filename | No | Filename override — its extension selects the converter (otherwise taken from the URL) | |
| created_by | No | Your name (e.g. "Codex", "Claude") so the user sees who made the document. Recommended. |
| Name | Required | Description |
|---|---|---|
| id | Yes | Document ID |
| url | Yes | Editor URL |
| notes | Yes | Human-facing claim and retention notes |
| title | Yes | Document title |
| edit_token | Yes | Bearer token scoped to this document for future read/edit calls |
| unlock_more | Yes | Agent-facing guidance for authenticating to unlock more tools |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond annotations, such as 'file bytes are never passed inline', the 7-day deletion if unclaimed, and the return of url and edit_token with usage instructions. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (6 sentences) and front-loaded with the core purpose. Every sentence adds necessary detail, with no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of an output schema, the description fully covers return values, lifecycle, and usage context. It is complete for an AI agent to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds extra context for the filename parameter ('its extension selects the converter') and recommends the created_by parameter, providing value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Create a Revise document from a file at a public http(s) URL.' It specifies supported formats and distinguishes from the sibling tool upload_document for local files, leaving no ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when not to use this tool ('For a LOCAL file, use upload_document instead') and lists supported URL types and formats. It implies usage for public URLs but lacks an explicit 'use this when' statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
insert_footnoteInsert footnoteAInsert a footnote: a numbered superscript reference placed immediately after the anchor text inside a paragraph, plus the footnote body (shown at the bottom of the page, or as an endnote in pageless documents). On substantial documents this lands as a pending tracked change by default, like edit_document. Footnote bodies appear in read_document as [^n]: definitions with their own block ids — edit or remove them with the normal editing tools (removing a footnote body also removes its reference, and vice versa).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Document ID | |
| find | Yes | Anchor text inside the block; the reference is inserted right after it. Pass an empty string to append at the end of the block. | |
| kind | No | Note stream: footnote (per-page bottom area, numbered 1,2,3 — default) or endnote (grouped on its own page at the document end, numbered i,ii,iii) | |
| mode | No | Omit for the default: suggest (pending tracked change) on documents with 20+ words, apply on shorter ones. Choose "apply" on a substantial document only when your user explicitly asked for direct edits without review. | |
| text | Yes | Footnote body text | |
| block_id | Yes | Paragraph block that gets the reference (from read_document with_block_ids) |
| Name | Required | Description |
|---|---|---|
| status | Yes | inserted directly, or left as a pending tracked change |
| suggestion_id | No | Pending suggestion id when status is suggested |
| footnote_label | No | Display label as it appears in the text: arabic for footnotes, lowercase roman for endnotes |
| footnote_number | No | Per-stream index of the new note |
| footnote_block_id | No | Block id of the footnote body (editable with block tools) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context about tracked changes and the relationship between footnote body and reference. However, the idempotentHint annotation (true) contradicts the description's implication that each call creates a new tracked change, suggesting potential idempotency issues.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, with one clear sentence stating the purpose followed by key behavioral details. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main aspects: insertion behavior, tracked changes, and management of footnote bodies. Given the complexity of 6 parameters and existing output schema, it provides sufficient context for tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage, but the description adds meaningful context beyond the schema, such as the behavior of 'find' (insert after anchor, empty appends), 'kind' (footnote vs endnote numbering), and 'mode' (default based on document size). This helps the agent understand parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Insert a footnote' and explains what a footnote consists of (numbered superscript reference and body). It distinguishes itself from siblings by detailing its specific placement within a paragraph.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool via the footnote concept, but it does not explicitly contrast with siblings like leave_comment or edit_document. It mentions similarity to edit_document for tracked changes but lacks explicit when-not or alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
leave_commentLeave a commentAInspectLeave a review comment in a document WITHOUT changing its text — either a new thread anchored to one block, or a reply to an existing thread. Comments appear in the editor's margin attributed to you, where the owner can reply or resolve. Prefer this for passage-specific critique or questions; to propose an actual text change, use edit_document in "suggest" mode instead. To START a thread: target one block (from read_document with_block_ids: true) and exactly one anchor form — anchor_text (short text occurring exactly once in the block), anchor_start_text + anchor_end_text (boundaries of a longer range, without reproducing it), or whole_block: true (structural or empty blocks). To REPLY: pass reply_to_comment_id (a comment id from a element in read_document format "html", or from an earlier leave_comment result) and no block/anchor fields. Text that already carries an unresolved is already under discussion: reply to that thread rather than starting a second one over the same words, which is rejected unless you pass acknowledge_existing_thread_ids.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Document ID | |
| comment | Yes | Comment body (Markdown) | |
| block_id | No | Target block for a NEW thread (from read_document with_block_ids: true). Required unless replying. | |
| anchor_text | No | Short exact text that occurs exactly once in the block; the comment anchors to it | |
| whole_block | No | Anchor to the entire block instead of a text range (structural or empty blocks) | |
| anchor_end_text | No | Exact text at the end of that range (pair with anchor_start_text) | |
| anchor_start_text | No | Exact text at the start of a longer range (pair with anchor_end_text) | |
| reply_to_comment_id | No | Reply to an existing thread instead of starting a new one: any comment id in the thread (the reply attaches to the thread root). Omit block_id and anchors when replying. | |
| acknowledge_existing_thread_ids | No | Only for a NEW thread that deliberately overlaps existing unresolved threads: list their ids to confirm you read them and are raising a genuinely different point. Without this, a new thread over text that already carries one is rejected. Do not use it to restate a point an existing thread already makes — reply to that thread instead. |
| Name | Required | Description |
|---|---|---|
| note | No | Review guidance |
| status | Yes | commented: new thread started; replied: reply added to an existing thread |
| block_id | No | Block the comment is anchored to (new threads only) |
| thread_id | No | Root comment id of the thread a reply was added to |
| comment_id | Yes | ID of the new comment or reply |
| anchored_text_range | No | Anchored character range within the block (text anchors only) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral context beyond annotations: it states comments appear in the editor's margin attributed to you, that overlapping threads are rejected unless the caller passes acknowledge_existing_thread_ids, and that replies attach to the thread root. It also clarifies the operation modifies the document's metadata, not its text, which aligns with destructiveHint=false. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is comprehensive yet tightly organized. It front-loads the core purpose, then flows through usage preferences, thread-starting rules, replying, and edge cases. Every sentence adds necessary operational detail; no filler is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 parameters, two modes, rejection rules), the description covers all relevant aspects: when to use, how to anchor, how to reply, how to handle existing threads, and the output source for thread IDs. The presence of an output schema reduces the need to describe return values, and the description provides all necessary context for a correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the input schema covers all parameters at 100%, the description enriches their meaning significantly. It explains the three mutually exclusive anchor forms (anchor_text, anchor_start_text + anchor_end_text, whole_block), the conditions for using reply_to_comment_id (no block/anchor fields), and the purpose of acknowledge_existing_thread_ids. This goes well beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-resource pair: "Leave a review comment in a document WITHOUT changing its text" and immediately distinguishes itself from edit_document. It clearly states the two supported modes (new thread anchored to a block, or reply to an existing thread), making the tool's scope unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: "Prefer this for passage-specific critique or questions; to propose an actual text change, use edit_document in 'suggest' mode instead." It also instructs when to reply versus start a new thread, and warns against creating overlapping threads, with an explicit alternative (reply to existing thread).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
read_documentRead documentARead a Revise document's content. Format "markdown" (default) is the simple dialect — best for plain prose; set with_block_ids to true to interleave anchors usable with edit_document. Format "html" is the full-fidelity dialect: compact HTML-like markup with a block id on every element plus everything markdown cannot express — rich marks, math, code block languages, merged table cells, page layout, and each comment thread inline as a wrapper around its anchored text. Prefer html when a document uses rich features or has comments; edit_document accepts the same dialect in replacements. "text" is plain text. (For a styled, self-contained HTML file, use export_document instead.) view controls how pending tracked-change suggestions read: "final" (default, as if accepted) or "original" (as if rejected). Long documents are paginated: when a read exceeds the character budget it is cut at a block boundary and the response carries truncated: true, next_start_block, and a ready-to-run example call — repeat with start_block to continue. For a targeted read of a large document, prefer get_document_outline + search_within_document over paging through everything.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Document ID | |
| view | No | Projection of pending suggestions: final = accepted (default), original = rejected | |
| format | No | ||
| start_block | No | 0-based top-level block index to start reading from (default 0). Use the previous response's next_start_block to continue a paginated read. | |
| with_block_ids | No | Interleave block id anchors (markdown format only) |
| Name | Required | Description |
|---|---|---|
| id | Yes | Document ID |
| note | No | Pagination guidance |
| format | Yes | Returned format |
| content | Yes | Document content in the requested format |
| truncated | No | True when the read was cut at a block boundary |
| start_block | No | First top-level block index included in this page |
| total_blocks | No | Total top-level blocks in the document |
| with_block_ids | No | Whether markdown block anchors were included |
| blocks_included | No | Top-level blocks included in this page |
| next_start_block | No | Pass as start_block to read the next page |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds critical behavioral details: pagination behavior, truncated responses, next_start_block, and ready-to-run continuation calls. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear hierarchy: core purpose, format options, view control, pagination. Every sentence provides actionable information with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, many siblings, output schema exists), the description covers all aspects: parameter details, return behavior (truncation, continuation), and appropriate tool recommendations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 80% schema coverage, the description adds significant meaning beyond the schema: it explains the trade-offs between formats, the purpose of with_block_ids, how view affects tracked changes, and the pagination mechanism for start_block.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a clear verb+resource ('Read a Revise document's content') and then elaborates on formats and features, distinguishing it from siblings like export_document and search_within_document.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use each format, when to enable with_block_ids, how to handle pagination, and recommends alternatives like get_document_outline + search_within_document for targeted reads.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
rename_documentRename documentCChange a document's title.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Document ID | |
| title | Yes | New document title |
| Name | Required | Description |
|---|---|---|
| title | Yes | New title |
| status | Yes | Rename status |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotent and non-destructive mutation, but the description adds no behavioral context beyond stating the action. No mention of side effects, permissions, or return value details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise single sentence, front-loaded and to the point. Could be improved by including constraints or usage context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple tool with two parameters and output schema. Description minimal but sufficient for basic understanding; lacks differentiation from similar tools in context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and parameters are well-described. The description does not add additional meaning beyond 'Document ID' and 'New document title'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Change a document's title.' clearly states the verb and resource, distinguishing it from siblings like edit_document or replace_document_content. However, it is somewhat tautological with the tool name and title.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, such as edit_document or replace_document_content. No prerequisites or exclusions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
replace_document_contentReplace document contentAReplace the ENTIRE content of a document with new markdown. Destructive: existing content is removed (it remains recoverable via the document's revision history). Prefer edit_document for targeted changes.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Document ID | |
| content_markdown | Yes | New full document content |
| Name | Required | Description |
|---|---|---|
| blocks | Yes | Number of blocks in the new content |
| status | Yes | Replacement status |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds that content is recoverable via revision history, which is additional context beyond the destructiveHint annotation. 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with action and resource, followed by destructive warning and usage guidance. Zero waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, behavior, and usage. Output schema exists so return details are covered. No gaps for a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions. Description emphasizes 'ENTIRE content' but adds little new meaning beyond schema. Baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'Replace' and resource 'entire content of a document' with specific format 'new markdown'. Distinguished from sibling edit_document for targeted changes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises to prefer edit_document for targeted changes, providing clear when-not-to-use guidance. Does not cover all siblings but sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
resolve_suggestionsAccept or reject your suggestionsAAccept or reject the tracked-change suggestions YOU made on a document — only your own, never the user's edits or another agent's suggestions. Use this when the user approves your suggested changes (e.g. they say "lgtm" / "looks good") to apply them on their behalf, or asks you to withdraw them. Covers the whole document by default; pass block_ids to limit to specific blocks. (Edits made with edit_document in "apply" mode are already applied — this is for edits left as suggestions in "suggest" mode.)
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Document ID | |
| kind | No | Limit to one kind of change (Word-style review filter): insert = added text/blocks, delete = removed text/blocks, format = formatting-only changes; omit for all kinds | |
| action | Yes | accept: apply your suggested changes; reject: withdraw them | |
| block_ids | No | Limit to suggestions in these blocks (from read_document with_block_ids); omit to review the whole document |
| Name | Required | Description |
|---|---|---|
| note | No | Why no suggestions were resolved |
| status | Yes | Suggestion resolution outcome |
| resolvedChangeRegions | No | Resolved change-region count |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (idempotentHint=true, destructiveHint=false), the description adds key behaviors: only works on the agent's own suggestions, covers whole document by default, allows filtering by block_ids, and is for suggestions mode only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences efficiently pack purpose, usage, scope, and parameter hints; front-loaded with main verb. Slight length in second sentence but justifiable given complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensive coverage of scope, action types, limitations, and filtering; output schema exists so return values not needed. Fully adequate for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds practical usage context (e.g., 'omit to review the whole document' for block_ids, 'from read_document with_block_ids' for sourcing, and action enum meanings).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it accepts or rejects the agent's own tracked-change suggestions on a document, distinguishing it from sibling tools like edit_document which handle direct edits.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use (when user approves or asks to withdraw), and clarifies not to use for user edits or other agents' suggestions, and that edit_document with apply mode handles direct edits.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_within_documentSearch within documentAFind where a query matches inside one document. Returns the matching blocks as markdown with anchors (usable with edit_document), each with a few neighboring blocks for context. Case-insensitive.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Document ID | |
| query | Yes | Text to find (case-insensitive) | |
| context_blocks | No | Neighboring blocks to include on each side (default 2) |
| Name | Required | Description |
|---|---|---|
| note | No | Result note or truncation guidance |
| query | Yes | Search query |
| groups | No | Context groups containing matches |
| totalMatchingBlocks | Yes | Matching block count |
| returnedMatchingBlocks | No | Number of matching blocks returned in this response |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that searches are case-insensitive, returns markdown with block anchors, and includes neighboring blocks for context—valuable behavioral details beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. Information is front-loaded: first sentence states core function, second adds key details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage, parameters, behavioral traits, and ties to sibling edit_document. With an output schema existing, the description completes the picture by describing the format of the output (markdown with anchors).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%. The description adds meaning by stating the default for context_blocks (2) and explaining the case-insensitive nature of the query, which is not in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('find'), resource ('one document'), and output ('matching blocks with anchors and context'), distinguishing it from siblings like read_document (whole document) and get_document_outline (structure).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for searching within a single document and mentions integration with edit_document via anchors. It does not explicitly exclude cross-document search or list alternatives, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
set_page_layoutSet page layoutASet a document's page layout: page size, orientation, margins, page numbers, line/paragraph spacing, pageless mode, or the APA-7 preset. Length values are strings with explicit units (e.g. "1in", "2.54cm", "72px").
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Document ID | |
| margin | No | Uniform margin for all sides, e.g. "1in" | |
| preset | No | Layout preset applied before other overrides | |
| pageless | No | Enable pageless (continuous) mode | |
| note_mode | No | Bulk-convert every note in the document to this stream: footnotes (per-page bottom areas, numbered 1,2,3) or endnotes (grouped on their own page at the end, numbered i,ii,iii). Individual notes choose their stream at insert time via insert_footnote | |
| page_size | No | Named page size | |
| watermark | No | Diagonal page watermark text painted on every page, e.g. "DRAFT" or "CONFIDENTIAL". Also accepts a JSON settings string {text, color?, opacity?, diagonal?, fontSizePx?}. Pass "" or null to remove the watermark | |
| margin_top | No | ||
| margin_left | No | ||
| orientation | No | ||
| margin_right | No | ||
| block_spacing | No | Vertical spacing between blocks, e.g. "0.125in" | |
| margin_bottom | No | ||
| line_numbering | No | Word-style line numbering in the left margin (pleading paper). Pass an object (possibly empty) to enable, null to disable | |
| page_number_start | No | ||
| show_page_numbers | No | Show/hide page numbers (managed as an automatic header/footer page-number field slot; hand-authored header/footer content is never overwritten) | |
| page_number_position | No |
| Name | Required | Description |
|---|---|---|
| status | Yes | Layout update status |
| applied | Yes | Applied layout settings |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral detail beyond the annotations: length values must use explicit units, note_mode bulk-converts between footnote/endnote streams, watermark accepts removal via empty/null, and show_page_numbers never overwrites hand-authored headers/footers. No contradiction exists with annotations (idempotentHint=true, readOnlyHint=false).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: one sentence enumerates the tool's scope and another gives crucial unit format info. There is no wasted wording, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 17-parameter tool, the description covers the main feature areas and critical behavioral nuances, and the output schema covers return values. It lacks explicit usage guidance and edge-case handling (e.g., conflicting margin parameters or preset interactions), but overall it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 59% schema coverage, the description compensates by explaining the unit format for length parameters (e.g., '1in', '2.54cm', '72px') and providing semantics for preset, note_mode, watermark, and line_numbering. It does not individually describe all uncovered params like margin_top or orientation, but the unit convention plus self-explanatory names offset the gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Set' with a clear resource ('document's page layout') and enumerates concrete aspects (page size, orientation, margins, page numbers, line/paragraph spacing, pageless mode, APA-7 preset). This clearly distinguishes it from sibling tools like style_blocks or edit_document.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for page layout adjustments by listing supported features, but provides no explicit when-to-use guidance or contrast with alternatives such as edit_document or style_blocks. There are no exclusion statements or conditions for when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
style_blocksStyle document blocksAStyle existing content with forgiving CSS-lite selectors and values. Use this for bulk formatting instead of rewriting text. Block selectors include , #blockId, p, h1-h6, li, lists, tables, and descendants. Inline selectors such as b/strong, i/em, u, s/strike/del, code, sup, sub, mark, and a target only matching formatted text ranges. Examples: set the entire document to Georgia with selectors="" and attrs=[{"name":"fontFamily","value":"Georgia"}]; bold headings with selectors=["h1","h2","h3"] and attrs=[{"name":"fontWeight","value":"bold"}]. Formatting lands as pending tracked changes by default on substantial documents.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Document ID | |
| mode | No | Omit for the default: suggest (tracked formatting changes) on documents with 20+ words, apply on shorter ones. Choose "apply" on a substantial document only when the user explicitly asks for direct formatting. | |
| attrs | Yes | Style attributes to set | |
| selectors | Yes | CSS-lite selectors: *, #blockId, p, h1-h6, li, ul, ol, pre, latex, img, table, tr, td/th, div, inline formatting tags, descendants, and :nth-child(n) |
| Name | Required | Description |
|---|---|---|
| note | No | Review guidance |
| status | Yes | Whether formatting was suggested or directly applied |
| selectorsRequested | Yes | Number of selectors in the request |
| attributesRequested | Yes | Number of style attributes in the request |
| pendingSuggestionIds | No | Tracked formatting suggestion IDs |
| acceptedChangeRegions | No | Formatting change regions accepted immediately |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations: 'Formatting lands as pending tracked changes by default on substantial documents' and explains mode defaults. This aligns with idempotentHint and destructiveHint, with no contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, well-structured, and front-loaded: it starts with purpose, provides usage guidelines, includes examples, and ends with behavioral notes. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 params, 3 required, output schema exists), the description covers selectors, attrs, mode, and default behavior adequately. It lacks error handling details but is sufficient for an AI agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents parameters well. The description reinforces meaning with examples but does not add substantial new information beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool styles existing content using CSS-lite selectors and values, distinguishing it from rewriting text. It specifies block and inline selectors, providing a precise verb-resource combination.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this for bulk formatting instead of rewriting text' and explains the mode parameter behavior (apply vs suggest). It provides examples but does not explicitly contrast with sibling tools like edit_document, though context implies appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
upload_documentUpload a document file (no account)AInspectCreate a Revise document from a LOCAL file (docx, md, txt, html; PDFs/images not yet supported) without a Revise account and without putting its bytes in your context. Returns a one-time upload_url and a ready-to-run curl command — run the curl to stream the file. The curl response contains url (give it to your user — they view the document and create a free account to keep it, in one step) and edit_token (your Bearer token for future edits). For a public http(s) URL or a tiny inline file, use import_document instead. The document is private and deleted after 7 days if unclaimed.
| Name | Required | Description | Default |
|---|---|---|---|
| filename | Yes | The file's name (its extension selects the converter) | |
| created_by | No | Your name (e.g. "Codex", "Claude") so the user sees who made the document. Recommended. |
| Name | Required | Description |
|---|---|---|
| curl | Yes | Ready-to-run curl command for the upload |
| next | Yes | What to do after reserving the upload |
| expires_in | Yes | Seconds until the upload URL expires |
| upload_url | Yes | One-time upload endpoint |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behavioral traits: the tool does not upload file bytes directly but returns a one-time upload URL and curl command; document is private and deleted after 7 days if unclaimed. This adds value beyond annotations, which only contain non-contradictory flags.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core action and supported file types. Every sentence serves a purpose without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (multi-step upload, return of upload_url and curl command), the description fully explains the process, file limitations, and account creation. An output schema exists, so return values are covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with good parameter descriptions (e.g., filename extension selects converter). The tool description does not add significant extra meaning beyond what the schema already provides, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the tool's purpose: creating a Revise document from a local file (docx, md, txt, html) without an account, and distinguishes it from import_document for public URLs. It uses specific verbs and resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool (for local files) and when to use the alternative (import_document for public URLs or inline files). Provides clear context and exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
