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

Annotations only supply destructiveHint=true; the description adds substantial behavior beyond that: the operation is in-memory and non-persisting, which document parts are swept, and the AMBIGUOUS_REVISION_OVERLAP hard-error with a structured overlaps list. This is exactly the context a mutation tool needs.

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?

Dense but front-loaded: the core action and the persistence caveat come first, then targeting, then scope, then the error case. Every sentence carries new information, though the error/overlap sentence is heavy enough to slow scanning slightly.

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 destructive mutation with no output schema, the description covers persistence implications, targeting modes, affected parts, and the failure mode. Nothing an agent needs to invoke it correctly is missing.

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 already 100%, so the baseline is 3. The description still adds value by clarifying that revision_ids are w:id values, that author is a convenience alternative, and that normalize_first is best-effort with no byte-identical promise — semantics that go beyond the schema wording.

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?

Opens with a specific verb+resource: 'Selectively accept tracked changes by revision id or author in the in-memory session.' The 'selectively' and 'leaving all other revisions byte-untouched' scope makes it clearly distinct from the siblings accept_changes and reject_ai_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 routes the agent: use revision_ids for specific revisions, author for a whole actor, and call save to persist since this tool does not write file_path. It also names the normalize_first fallback condition, so the agent knows when to reach for each option.

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

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

Annotations already disclose readOnlyHint=false and destructiveHint=true, so the mutation risk is covered. The description usefully adds the scope ('document body') and the unsupported-marker caveat ('unresolvedRowRevisions remains 0 for supported row markers'), which is genuine extra context, but it does not state irreversibility or whether the result is persisted to disk or requires a separate save.

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 action and scope, and the second sentence carries the return-value caveat. Dense and largely waste-free, though the 'acceptance stats' clause is slightly vague.

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 single-parameter destructive mutation with no output schema, the description covers scope, the supported-change limitation, and a return-value detail. The main gap is persistence behavior and the boundary against accept_ai_edits, but the destructive annotation already conveys the safety profile.

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 (file_path) with 100% schema description coverage, so the schema fully documents it. The description adds nothing about file_path semantics (format support wording mirrors the schema), so the 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?

States a specific verb and resource ('Accept every supported tracked change in the document body') and narrows scope with 'supported' plus table-row revision handling. However, it never distinguishes itself from the sibling accept_ai_edits/reject_ai_edits tools, leaving the agent to infer which accept variant applies.

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 when-to-use guidance is given — no prerequisites, no mention of when to prefer this over accept_ai_edits or how it pairs with extract_revisions/has_tracked_changes. The agent must guess the workflow context.

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

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

Explains beyond annotations: it is revisionable with tracked changes (w:ins) in body-story, and comment text/author metadata recorded in non-revision change manifest. Also notes ODT format behavior (office:annotation). Annotations only indicate destructiveHint=true, so this adds significant value.

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 moderately long but well-structured: starts with main purpose, then usage patterns, format differences, and behavioral details. Every sentence adds value, though it could be slightly shortened without losing clarity.

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 7 parameters, no output schema, and complexity of threaded comments vs root, the description covers purpose, parameter use cases, format limitations, and behavioral impact. It does not explain return values, but that is acceptable without an output schema. Slightly more could be done to clarify prerequisites or error conditions.

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 meaning by explaining two usage patterns (root vs reply), the effect of omitting anchor_text (anchors to entire paragraph), and defaults for initials. This goes beyond the schema's 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?

Clearly states the tool adds comments or threaded replies, distinguishes two modes (root vs reply), and specifies supported formats (DOCX, ODT) with DOCX-only for threaded replies. This distinguishes it from sibling tools like delete_comment or get_comments.

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 instructions on when to use target_paragraph_id+anchor_text versus parent_comment_id, and notes format-specific limitations. However, it does not explicitly state when not to use this tool or compare it to alternatives like batch_edit or insert_paragraph.

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

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

Beyond annotations ('destructiveHint: true'), the description details revision tracking behavior: footnote reference and text are tracked as insertions, while footnote-part creation is recorded in the save report as non-revision changes. This provides valuable context for AI 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 concise with two sentences and a note. The first sentence plainly states purpose, the second adds optional parameter. The technical note about revision tracking, while dense, is relevant for transparency. Could be slightly streamlined.

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 no output schema, the description adequately covers what happens on invocation: tracked changes and save report details. It explains the effect of 'after_text' and the revision behavior, leaving little ambiguity 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 description coverage is 100%, so the baseline is 3. The description adds minimal extra semantics, only clarifying that 'after_text' is optional and used for positioning. No additional depth beyond 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 ('Add') and resource ('footnote anchored to a paragraph'), distinguishing it from sibling tools like 'update_footnote' and 'delete_footnote'.

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 indicates when to use this tool (to add a footnote) and mentions optional positioning with 'after_text', but lacks explicit guidance on when not to use it or alternatives beyond the sibling list.

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

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

Annotations indicate destructiveHint=true and readOnlyHint=false. The description adds valuable behavioral details: validates all steps first, rejects conflicts, executes sequentially, and emits tracked changes, going beyond annotation-only information.

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 concise sentences, each adding essential information without redundancy. Purpose, behavior, and outcome are clearly communicated with no 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 key aspects: batch operation, validation, conflict handling, and output (tracked changes). However, lacks details on error handling for individual step failures or partial execution, leaving some gaps for complex scenarios.

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%, baseline 3. The description adds meaning by explaining that steps can be inline or via plan_file_path, and that each step needs step_id, operation, and operation-specific fields, compensating for the schema's empty items properties.

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 is for applying multiple edit steps (replace_text, insert_paragraph) to a document in one call, distinguishing it from individual sibling tools like replace_text and insert_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?

It identifies itself as a 'single-agent front door' for batch edits, implying usage for multiple steps. It mentions validation and conflict rejection but does not explicitly state when not to use it or compare to alternatives beyond the sibling list.

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

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

Annotations indicate destructiveHint=true, but the description adds important context: the operation is revisionable and emits a native run-property-change revision. This goes beyond annotations and helps the agent understand the side effects.

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 concise sentences with no wasted words. The first sentence states the core function, the second adds behavioral context. Well-structured and 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?

With 8 parameters (1 required) and no output schema, the description covers purpose, behavior (revisionable), and scope (paragraphs). It could mention error conditions or file modification details, but the combination with schema annotations is fairly 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?

The schema has 100% coverage with descriptions for all parameters. The description repeats the list of formatting types but adds context about run-level and revisions. Since schema coverage is high, baseline is 3; the description offers moderate added value.

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 clears specific run-level formatting (bold, italic, underline, highlight, color, font) from paragraphs, which is a specific verb+resource. It distinguishes from sibling tools like format_layout which likely deals with layout-level formatting.

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 clearing run-level formatting but does not explicitly state when to use this tool versus alternatives (e.g., format_layout). No exclusions or when-not-to-use guidance is provided.

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

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

Annotations already declare destructiveHint=true. The description adds supported file formats but does not disclose what happens to unsaved changes or other side effects of closing. Some additional behavioral context would be beneficial.

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 a single sentence that efficiently conveys the core purpose. It is front-loaded and contains no unnecessary words, though a bit more structure (e.g., separate lines for usage) could improve readability.

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 no output schema and the destructive nature, the description is minimal. It does not explain return values, side effects, or parameter interactions. For a closing tool, more detail on what happens after closing (e.g., saving) would improve completeness.

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 50%, but the description does not explain any parameter semantics. It does not clarify the roles of clear_all and confirm (which lack schema descriptions), nor does it add meaning beyond the schema for file_path and google_doc_id.

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 a specific verb ('close') and resource ('open file session'), and distinguishes from sibling tools like read_file, save, and batch_edit by clearly indicating this is about closing sessions. It also specifies supported file formats.

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 when an open file session exists and mentions explicit confirmation for closing all sessions, but provides no when-not guidance or alternatives. It lacks details on prerequisites or comparison to other closing scenarios.

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

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

Annotations only supply readOnlyHint/destructiveHint; the description independently discloses deep behavior: unexposed selectors, revised-archive package base, insertion/deletion counting semantics with atomMetricVersion, formatChanges vs modifiedParagraphs, the unrepresented_changes/warnings contract, warning-message emission, and detector scope limits. This is exactly the beyond-annotations context the rubric rewards.

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 purpose is front-loaded, but the definition is a single sprawling paragraph dense with implementation jargon (CT_SdtPr, w:sdtPr/w:sdtEndPr, tagged-token-v1) that would benefit from separation into mode, output, and warning sections. Every clause is informative, but the packing hurts scannability.

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 two-mode, seven-parameter tool with no output schema, the description covers both invocation modes, DOCX vs ODF granularity, output statistics fields, and the warning/unrepresented_changes return contract. An agent has enough to call it correctly and interpret the result.

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 3 is the baseline, but the description goes further by explaining how parameters interact (which two paths select standalone mode, which single path selects session mode) and clarifies that certain selectors are deliberately not exposed. That is semantic value the schema alone does not convey.

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?

Opens with a concrete verb+resource+artifact: 'Compare two documents and produce a tracked-changes output document.' That instantly distinguishes it from siblings like has_tracked_changes (detection only) and extract_revisions (reads existing markup), since this one generates a new revision-marked 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?

It gives explicit parameter-driven mode selection: original_file_path + revised_file_path for standalone comparison versus file_path to compare session edits against the original. That is clear contextual guidance, but it never names a sibling alternative or a when-not-to-use condition, so it stops short of a 5.

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

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

The description details the write operation, safety validation, lossy nature with specific mapped and unmapped constructs, and return values. This goes well beyond the annotations, which only indicate non-read-only and non-destructive.

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 with three sentences, each adding essential information. It is front-loaded with the core action and avoids 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?

The description fully covers inputs, output, processing details, limitations, and return value structure. Without an output schema, it adequately explains what the tool returns.

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 description adds no extra parameter meaning beyond what the schema provides. Baseline 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 precisely states the tool converts DOCX to ODT using a native converter, lists what is preserved and lost, and notes unsupported inputs. It clearly distinguishes from sibling tools like 'export' by specifying the conversion direction and limitations.

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 states the input requirement (DOCX) and output format (ODT), and lists unsupported features. However, it does not explicitly state when to avoid this tool or suggest alternatives among siblings.

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

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

Annotations indicate destructiveHint=true. The description adds valuable behavioral details: cascade-deletes all descendants and specifics about tracking (w:del, non-revision change manifest). This goes beyond the annotations, disclosing side effects and recording behavior.

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, each serving a purpose. The first sentence is a clear action, the second adds technical behavioral context. Front-loaded but the second sentence may be dense; still efficient with no wasted words.

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 simple delete tool with 2 parameters and no output schema, the description covers the core action and side effects. However, it lacks information on error conditions, prerequisites (e.g., file must be open), or what the response looks like, leaving some 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?

Schema coverage is 100% with descriptions for both parameters. The tool description does not add extra meaning or syntax details beyond the schema, meeting the baseline for high coverage.

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 action ('Delete a comment and all its threaded replies') and identifies the resource (comment). It distinguishes this tool from siblings like add_comment or get_comments by specifying deletion of threaded replies.

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 use for deleting comments but does not explicitly state when to use or avoid this tool, nor does it mention alternatives (e.g., delete_footnote). Some context is given but lacks explicit guidance.

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

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

Annotations already indicate destructiveHint=true. The description adds valuable detail: that the deletion is revisionable and performed as native OOXML tracked deletions (w:del), providing transparency beyond the annotations. 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 concise sentences, front-loaded with the primary action. Every sentence adds value: purpose and technical detail. No wasted words.

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 simple tool with 2 required parameters and no output schema, the description is complete. It explains the core behavior and tracked changes mechanism. Could optionally mention that note_id should come from get_footnotes, but not necessary for completeness.

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% (both parameters described in schema). The description adds no additional meaning beyond the schema, but the schema itself is clear. 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 deletes a footnote and its reference, distinguishing it from sibling tools like add_footnote and update_footnote. The verb 'delete' combined with the resource 'footnote' gives unambiguous purpose.

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 explicit when-to-use or when-not-to-use guidance is provided, nor are alternatives mentioned. However, the context from sibling tools makes it clear this is the deletion tool, providing some implicit guidance. Could be improved by noting prerequisites or limitations.

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

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

Beyond annotations (both false), the description details output file writing, return values (path, byte count, content), lossy behavior, and semantic HTML nature. This fully discloses behavioral traits.

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 main action, no wasted words. Every sentence provides essential information: purpose, output behavior, and limitations.

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 5 parameters and no output schema, the description covers all needed context: formats, output file behavior, return values, and constraints (DOCX only, lossy). It is fully sufficient for agent understanding.

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 value by explaining default output path behavior and the return of rendered content under 'content', which clarifies the include_markdown parameter's effect.

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 exports a document to Markdown, HTML, or plain text. It distinguishes from siblings like convert_to_odt by focusing on rendering formats, and specifies DOCX-only, providing a specific verb and resource.

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 clear context (DOCX only, not Google Docs) but does not explicitly state when to use this tool over alternatives. However, siblings are distinct, so it is sufficient for guiding usage.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description confirms the read-only nature while adding real behavioral detail: how row-level insertions/deletions/format changes are surfaced with scope "row" and ROW_INSERTION/ROW_DELETION/FORMAT_CHANGE records, and that pagination is supported. This goes beyond what the annotations convey.

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 main purpose is front-loaded in the first sentence, followed by necessary detail on row-scope records and pagination. The middle sentences are dense and technical but each carries useful semantics rather than filler.

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?

With no output schema, the description carries the burden of explaining return values, and it does so well (before/after text, revision details, comments, row-scoped records). The only minor gap is that it doesn't restate accepted file types (DOCX/ODT, which the schema covers) or the author/date fields' format.

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 file_path, offset, and limit are already documented with ranges and defaults. The description only notes that pagination exists via offset and limit, adding no syntax or format detail beyond the schema; baseline 3 applies.

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?

States a specific verb (Extract) and resource (tracked changes) plus the output shape (structured JSON with before/after text per paragraph, revision details, comments). Clear enough to distinguish from the sibling has_tracked_changes, which only checks presence.

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?

Usage is implied by the purpose but never stated as when/when-not. It does not route the agent to siblings such as has_tracked_changes (to check first) or accept_changes/reject_ai_edits (to act on the revisions), so no explicit selection guidance is given.

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

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

The description goes beyond annotations by detailing that edits are revisionable (emit native property-change revisions) and notes platform-specific behavior. Annotations already indicate destructiveHint=true, and the description adds valuable context about tracked changes.

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: two sentences that front-load the purpose and then add key behavioral context. Every sentence adds value.

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 (6 parameters with nested objects, no output schema), the description lacks detail on how to use parameters (e.g., row_indexes, cell_indexes) and the meaning of 'strict'. It does not cover return values or error conditions.

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 only 33% (only file_path and google_doc_id have descriptions). The description does not explain the semantics of parameters like 'strict', 'row_height', 'cell_padding', or 'paragraph_spacing' beyond naming the categories. An agent would need more detail to set these correctly.

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 layout controls (paragraph spacing, table row height, cell padding). It differentiates from sibling tools like 'clear_formatting' by focusing on specific layout properties.

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 mention of 'Google Docs supports paragraph spacing only' provides some context about when to use which parameter, but there is no explicit guidance on when to use this tool versus alternatives like 'clear_formatting' or 'insert_paragraph'. Usage context is implied but not fully elaborated.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, but the description goes further by disclosing that effective edits emit a native w:pPrChange and that identical requests are no-ops. This tracked-change and idempotency behavior is exactly the kind of trait annotations cannot convey.

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 the core action, then modes, then constraints and behavioral footnote. No filler; every sentence carries distinct, useful 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?

For a single-paragraph mutation tool with full annotation coverage and complete schema descriptions, the definition covers purpose, modes, and side effects well. It stops short of describing the return value, which is notable given there is no output schema, but the core call contract is 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?

Schema coverage is 100%, so each parameter is already documented, but the description adds genuine value by explaining how the parameters combine (three mutually distinct edit modes) and the semantic result of each. It doesn't add syntax detail beyond the schema, so it stays just above the baseline.

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?

States a specific verb (Change) and precisely scoped resource (one DOCX body paragraph's direct numbering reference), immediately clarifying it operates on direct w:numPr rather than style-inherited numbering. An agent can distinguish this from generic formatting or numbering-creation tools without opening the schema.

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?

Gives explicit parameter-driven modes of use (remove=true, match_paragraph_id, num_id with ilvl) plus clear exclusions: it does not create numbering definitions or modify style-inherited numbering. This tells the agent both when and when-not to reach for this tool.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation profile is known. The description adds substantive behavioral context beyond that: effective calls emit exactly one native w:sectPrChange and preserve section topology, page-number format, columns, break type, and header/footer references, plus the non-obvious caveat that orientation is literal and does not auto-swap dimensions.

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 tightly packed sentences with no filler; the updatable fields and the required index source are front-loaded, and the preservation guarantees and non-goals follow. Every clause carries operational 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?

For a 6-parameter mutation tool with nested margin/page_size objects and no output schema, the description covers the mutation semantics, preservation guarantees, and scope limits, which is nearly everything an agent needs. It does not restate return values, appropriately relying on the absence of an output schema.

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 the baseline is 3. The description adds meaning beyond the schema by clarifying that section_index must be a zero-based index sourced from get_sections and that orientation is literal rather than dimension-swapping, which directly prevents a common invocation error.

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?

States a specific verb (partially update) and a precise resource (one DOCX section's page-number restart, page dimensions/orientation, or margins). It names the sibling that supplies the required index (get_sections) and sets clear scope boundaries against insert_section_break and format_layout by ruling out section creation.

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 directs the agent to obtain section_index from get_sections and states the negative conditions ('does not create sections or edit header/footer content'). It stops short of naming when to prefer format_layout or batch_edit for broader formatting, so it is clear context without full alternative routing.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the description's 'Read-only' is consistent. It adds value by listing specific return fields and mentioning threaded replies and optional range-anchored fields, which go beyond what annotations provide. No contradictions are present.

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 consists of two sentences that front-load the core purpose ('Get all comments from the document') and then expand with relevant details. Every sentence adds value without redundancy. It is efficiently structured for quick parsing by an AI agent.

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 a single parameter, 100% schema coverage, and no output schema, the description sufficiently covers the return values (IDs, authors, dates, text, anchored paragraph IDs, and optional span fields). The mention of threaded replies and supported formats completes the picture for a read-only comment retrieval 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?

The input schema has 100% coverage with a single 'file_path' parameter described as 'Path to the DOCX or ODT file.' The description does not add additional meaning beyond what the schema already provides, so a 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 begins with a clear verb+resource combination ('Get all comments from the document') and lists specific fields (IDs, authors, dates, text, anchored paragraph IDs). It distinguishes itself from sibling tools like add_comment or delete_comment by focusing on retrieval. The mention of range-anchored DOCX comments and threaded replies adds specificity without 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 states it supports DOCX and ODT formats and is read-only, which implicitly guides when to use (read scenarios) versus write operations (e.g., add_comment, delete_comment). It does not explicitly exclude use cases or list alternatives, but the context of sibling tools provides sufficient differentiation.

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

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

Annotations already cover the safety profile (readOnly, non-destructive), so 'Read-only' is redundant. The description earns credit elsewhere: it discloses the deterministic-vs-heuristic source split, the precedence order word_style > list_metadata > outline_level, and that Markdown clamps ATX depth to 6 while JSON preserves 1-9.

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?

Purpose and scope are front-loaded, and the sentence enumerating source types is dense but each element carries information. The source lists are long, but they define the actual selection contract, so little is wasted.

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?

With no output schema, the description carries the return-value burden and does so by specifying the entry shape {paragraph_id, text, level, source} and the format-dependent level behavior. Minor gaps remain (no pagination/size hints for large documents), but it is largely complete for a read 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, but the description adds meaning beyond the schema: the precedence order governing the deterministic sources and the level-preservation difference between json and markdown formats. This genuinely clarifies parameter effects rather than restating them.

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?

States a specific verb and resource ('Get a compact structural map of a document's headings') and scopes it ('DOCX only'), so an agent can distinguish it from siblings like get_sections or read_file. It stops short of explicitly naming an alternative, so it doesn't reach the top of the scale.

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 gives the DOCX-only constraint and explains when to flip include_heuristic_headings=true, which implies usage. However, it never states when NOT to use this tool or which sibling to reach for instead (e.g., get_sections for full content), leaving routing to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, indicating safe read operation. Description adds minimal context about return data (edit count, normalization stats, cache info) but does not elaborate on side effects or limitations.

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, focused sentence with no extraneous information. Front-loaded with core purpose.

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 no output schema, description adequately hints at return values. Combined with strong annotations, it provides sufficient context for a simple metadata retrieval 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?

Input schema has 100% coverage with clear descriptions for both parameters. Description mentions supported formats (DOCX, ODT, Google Docs) which aligns with schema, but adds no additional semantic detail.

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?

Description clearly states 'Get file/session metadata' with specific examples (edit count, normalization stats, cache info), and mentions supported formats. This distinguishes it from sibling tools like get_comments or get_footnotes.

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 explicit guidance on when to use this tool vs alternatives. While it lists supported file types, it does not specify contexts where get_file_status is preferred over other metadata tools.

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

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

Description adds 'Read-only' and lists returned data (IDs, display numbers, text, anchored paragraph IDs). Annotations already provide readOnlyHint=true and destructiveHint=false, so description adds minor context beyond annotations but does not contradict.

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 efficiently conveys purpose, scope, and data returned with no wasted words. Front-loaded with key action 'Get all footnotes'.

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 simple read-only tool with one parameter and no output schema, description covers returned data and read-only nature. Lacks error handling or prerequisite info, but is sufficient for basic use.

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 has 100% coverage with file_path fully described. Description adds no additional parameter information beyond schema, meeting baseline expectation.

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?

Description explicitly states 'Get all footnotes from the document' with specific attributes (IDs, display numbers, text, anchored paragraph IDs), clearly distinguishing it from sibling tools like add_footnote, delete_footnote, update_footnote.

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?

Description states 'Read-only,' implying no modifications, but does not explicitly contrast with alternatives or provide when-not-to-use scenarios. Lacks explicit guidance relative to siblings, but the read-only nature is clear.

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

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

With readOnlyHint=true and destructiveHint=false already declared, the description's 'Read-only' adds nothing new, but it does disclose non-obvious behavior: the cache-staleness rule (re-call after topology changes) and that indices are session-relative rather than persistent. That is real behavioral context beyond 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, front-loaded with the core verb+resource before the return-value and re-call details. Slightly dense in enumerating return fields, but each clause carries information, and the trailing 'Read-only' is a minor redundancy against the 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?

No output schema exists, so the description helpfully enumerates the return surface (section_index, boundary metadata, page numbering, size, margins, header/footer refs). Combined with the staleness rule, an agent has enough to call it correctly; only the choice between this tool and get_document_outline is left unaddressed.

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 both file_path and google_doc_id are fully documented in the schema, including the URL-extraction hint. The description adds no parameter meaning at all, so the baseline 3 applies when the schema does the heavy lifting.

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?

States a specific verb and resource: 'Read DOCX main-document sections in document order,' and names the key return artifact (zero-based session-relative section_index values). It distinguishes itself from generic reads like read_file/grep by scoping to section topology, but never explicitly contrasts with the nearby get_document_outline sibling.

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?

'Call again after any operation that changes section topology' gives one concrete re-invocation trigger, which is genuinely useful. However, there is no guidance on when to prefer this over get_document_outline, read_file, or extract_revisions, leaving the agent to infer the choice among several read-oriented siblings.

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

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

Annotations declare readOnlyHint and destructiveHint, confirming safety. The description adds behavioral context: it searches paragraphs with regex, specifies input modes, and notes ODT-only support via file_path. No contradictions. Additional details about regex flags or output format would improve transparency.

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: two sentences that front-load the core action ('Search paragraphs with regex') and efficiently convey key usage distinctions. No redundant or unnecessary text.

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 (12 parameters, no output schema, low schema coverage), the description is insufficient. It does not explain return values (e.g., matching paragraphs), result limits, or behavior of regex flags, leaving significant gaps for an agent to use the tool 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 low (42%), and the description adds meaning to only the file/file-path parameters (file_path, file_paths, google_doc_id) and ODT support. The remaining 7 parameters (e.g., pattern, case_sensitive, max_results) lack description in both schema and tool description, leaving their semantics unclear.

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: 'Search paragraphs with regex.' It specifies different input modes (file_path, file_paths, google_doc_id) and highlights the ODT limitation, effectively distinguishing it from sibling tools like read_file or replace_text.

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 guidance on when to use different input parameters (session-based vs stateless multi-file vs Google Docs) and notes ODT support limitations. However, it lacks explicit guidance on when not to use this tool or alternatives among siblings.

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false. The description adds which marker types are checked but does not describe the return value or error behavior. Since no output schema exists, this is a minor gap.

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, no redundant information. Highly concise and 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?

For a simple boolean check tool, the description is adequate but omits return type and error cases. Given no output schema, agents may not know if the result is a boolean or something else. However, the parameter is well-documented.

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 with a clear description for file_path. The tool description does not add anything beyond that, 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 checks for tracked-change markers with specific types (insertions, deletions, moves, property-change records) and declares it read-only. This distinguishes it from sibling tools like accept_changes or extract_revisions.

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. For example, it doesn't suggest using it before accept_changes or that it's lighter than extract_revisions. The purpose implies usage but is not explicit.

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

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

Annotations already flag readOnlyHint=false and destructiveHint=true, so the mutation profile is known; the description adds genuinely useful context beyond that: DOCX insertions emit native OOXML tracked changes (revisionable surface) and ODT paragraph ids are positional and shift after insertion. It does not state permission/auth requirements or whether the operation can be undone outside tracked changes.

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 tight sentences with the core action front-loaded, followed by supported surfaces and then caveats. The parenthetical ODT warning and tracked-changes note both earn their place; no redundant filler.

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 7-parameter mutation tool with no output schema and only a destructive hint in annotations, the description covers supported formats, the id-shifting hazard, and tracked-changes behavior. It leaves the required 'instruction' parameter and any auth requirements for Google Docs unexplained, so it is strong but not fully 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?

Schema coverage is 57%, with the two most consequential parameters (positional_anchor_node_id and the enum position) already documented in the schema, and the description reinforces the anchor/position relationship. Two required parameters, new_string and instruction, have no explanation in either the schema or the description, so the description does not fully compensate for the coverage 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 names a specific verb (insert) and resource (paragraph) and pins down the mechanism: before/after an anchor paragraph identified by paragraph id. This clearly separates it from sibling tools like replace_text or insert_section_break, which operate on different targets.

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 use case is implied by 'insert a paragraph before/after an anchor paragraph,' and the ODT caveat tells the agent to re-read before further edits. However, there is no explicit when-to-use/when-not guidance and no reference to alternatives such as replace_text or batch_edit for related edits.

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

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

Annotations already declare destructiveHint=true, so the mutation profile is known. The description adds real value beyond that: the break is tracked, existing page setup and header/footer relationship references are preserved, inheritance of non-relationship properties defaults on, and — most importantly — section indexes shift after success, requiring a re-read. Return format is unstated, but the actions needed to stay consistent are.

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 verb+resource is front-loaded, and each subsequent sentence carries a distinct piece of information (preservation, inheritance, override, follow-up). It is dense and information-packed rather than padded, though the parameter detail could be tightened slightly.

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 mutating tool with nested objects and no output schema, the definition covers the important ground: tracked-change behavior, preservation semantics, inheritance defaults, override options, and the index-invalidation side effect. Only error conditions and explicit sibling routing remain uncovered, which is a minor gap.

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 the baseline is 3, but the description adds genuine interpretation: inherit_properties resets only non-relationship properties (header/footer refs always preserved), and new_section supplies optional page-number/page-size/margin overrides for the following section. This clarifies the interaction between the two parameters in ways the schema properties alone do not.

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?

States a specific verb and resource ('Insert a tracked DOCX section break') with the anchoring condition ('after a stable direct-body paragraph'). This is clearly distinguishable from read-only siblings like get_sections and from format_section, which modifies an existing section rather than inserting a boundary.

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 operational context: default inheritance behavior, how to opt out via inherit_properties=false, and the explicit follow-up 'Call get_sections again after success because section indexes change.' It does not, however, contrast this tool with alternatives like insert_paragraph or state when-not-to-use conditions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds real behavioral value beyond that: the default output is token-limited to ~14k tokens and the response carries pagination metadata (has_more, next_offset), which an agent needs to avoid truncated reads.

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 short sentences, front-loaded with purpose, then output truncation behavior, then the pagination remedy. Every sentence carries distinct information with no 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?

For an 11-parameter tool with no output schema, the description supplies the essential return-shape facts (14k token cap, has_more/next_offset) that the schema cannot. It does not describe the paragraph/ID structure of the content payload, but that gap is partly mitigated by the extensive per-parameter schema documentation.

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 91%, so individual parameters (including the deep footnote/fingerprint options and comment_rendering modes) are documented in the schema itself. The description restates offset/limit and the three input formats but adds no syntax or edge-case meaning beyond the schema, so the baseline 3 applies.

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?

States a specific verb and resource ('Read document content') and enumerates the supported source types (DOCX, ODT, Google Doc), which lets an agent separate it from outline/section/grep siblings by intent. It never names a sibling to route against, so it stops short of full discrimination.

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 only usage instruction is 'Use offset/limit to paginate,' which tells the agent how to handle the large-output case but not when to prefer read_file over get_document_outline, grep, or get_sections. Usage is implied by the pagination coaching rather than stated with alternatives or exclusions.

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

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

Annotations only say destructiveHint=true; the description goes well beyond by disclosing that the mutation is in-memory and non-persistent, that it sweeps document.xml plus supported side-story parts, that all other revisions are byte-untouched, and that overlap triggers a hard error with code AMBIGUOUS_REVISION_OVERLAP and a structured overlaps list. This is exactly the behavioral context annotations cannot carry.

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 dense sentences, front-loaded with the verb and scope, then persistence, then error behavior. Every clause carries new information, though the final sentence is packed with jargon (side-story parts, normalize_first) that slows parsing slightly.

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 mutating, non-persisting tool with no output schema, the description covers the persistence contract, the affected document scope, and the failure mode with its error code and payload. Nothing an agent needs in order to invoke it correctly is missing.

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 the baseline is 3, but the description adds cross-parameter meaning the schema lacks: revision_ids and author are alternative selectors, and normalize_first is a lossy escape hatch from the ambiguity error rather than a routine flag. The parenthetical on the error path is the main added value.

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?

States a specific verb and resource ('reject tracked changes'), the selection keys (revision id or author), the scope ('in the in-memory session'), and the effect on untouched revisions. It also explicitly positions itself against the sibling accept_ai_edits and against save, so the agent can distinguish it without opening a schema.

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 this tool does not write file_path and that save must be called to persist — a when-to-use and what-to-do-next instruction that would otherwise be a common agent mistake. It names accept_ai_edits as the symmetric counterpart and gives the exact condition (normalize_first) for avoiding the ambiguous-overlap hard error.

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

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

Annotations already declare destructiveHint=true, but the description adds substantial context beyond them: revisionable surface with native OOXML tracked changes (w:ins/w:del/w:rPrChange), the clean-save-deletes vs tracked-save-retains distinction, and the structural hazards that make deletion unsafe. This is exactly the added value annotations cannot carry.

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?

Front-loads purpose and supported formats, then layers the deletion shortcut and its caveats, then the revisionable surface note. Dense but every sentence carries operational information; the warning sentence is long but justified by its safety 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?

No output schema exists, yet the description conveys the key post-call behavior (tracked vs clean save outcomes) and the formats supported. It does not describe the response payload shape, which is a minor gap for a mutation tool of this 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 57%, and the description adds semantics for old_string/new_string in the deletion shortcut (complete visible text) and mentions the paragraph-id acceptance. However instruction, normalize_first, file_path, and google_doc_id are left to the schema, so the description only partially compensates for the coverage 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?

States a specific verb and resource — 'Replace text in a paragraph by provider paragraph id' — plus the scope (formatting preservation, supported formats DOCX/ODT/Google Docs). This clearly distinguishes it from insert_paragraph or batch_edit without opening schemas.

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?

Gives explicit when-to-use guidance (replace text by paragraph id), an alternative mechanism (empty new_string to delete a DOCX body paragraph), and explicit when-not-to warnings (section properties, table cell structural paragraphs, bookmark/comment anchors). Nothing is left to inference.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=true; the description goes well beyond that by disclosing the "revisionable" surface and the contents of the save report (AI revisions plus a non-revision change manifest of package-level mutations with no tracked-change wrapper). That is genuine behavioral context an agent could not infer. It omits any warning about the destructive overwrite path despite allow_overwrite existing, which keeps it out of the top tier.

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 core purpose is front-loaded in the first sentence, followed by format-specific behavior and then the save-report contract. It is dense and jargon-heavy ("non-revision change manifest of any package-level mutations") but every sentence carries distinct information with little 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?

With 11 parameters, no output schema, no title, and only safety annotations, the description does useful work by describing the save report in place of a return schema and covering all three target formats. It still leaves the relationship among file_path, save_to_local_path, tracked_save_to_local_path, and allow_overwrite unresolved, which is a meaningful gap for a destructive write tool with this many inputs.

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 55%, so the schema already carries substantial parameter documentation (notably the very detailed clean_bookmarks field). The description adds only indirect meaning, mapping "clean and/or tracked" to the save_format options, and leaves key parameters like allow_overwrite, file_path vs save_to_local_path vs tracked_save_to_local_path unexplained. Baseline 3 is appropriate for this coverage level.

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 ("Persist the current in-memory document session") and then enumerates concrete per-format outcomes for DOCX, ODT, and Google Docs. An agent can tell this writes the session to durable storage rather than merely closing it. It stops short of naming siblings (export, close_file) as alternatives, so it is clear but not sibling-differentiated.

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?

Format-specific behavior is spelled out ("For DOCX: saves clean and/or tracked changes output", "For Google Docs: checkpoint (default) returns revisionId, or snapshot exports as DOCX"), which implies when each mode applies. However, there is no explicit when-to-use-vs-alternative guidance in the description itself — the pointer to compare_documents lives in a schema field, not here. Usage is implied rather than stated.

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

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

The description adds value beyond annotations by disclosing that changes emit native OOXML tracked changes (w:ins/w:del). Annotations already show readOnlyHint=false and destructiveHint=true, but the description clarifies the revisionable nature, enhancing transparency.

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 sentences with no redundant information. First sentence states the core purpose; second sentence adds a critical behavioral detail. Every word is purposeful.

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 tool with three simple parameters, no output schema, and clear annotations, the description provides sufficient context. It covers purpose and a key behavioral trait (tracked changes), making it complete for its 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%, so the description does not need to add much. It provides general context but does not elaborate on parameter formats or constraints beyond what is in 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 tool updates the text content of an existing footnote. It uses a specific verb ('Update') and resource ('footnote'), distinguishing it from siblings like 'add_footnote' and 'delete_footnote'.

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 updating footnote text but does not explicitly state when to use this tool versus alternatives or any prerequisites. The behavioral note about tracked changes is helpful but does not provide direct usage guidance.

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