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

Annotations already indicate destructiveHint=true, and the description adds substantial behavioral detail: non-targeted revisions remain byte-untouched, multiple document parts are swept, and ambiguous overlaps cause a hard-error with a structured error code and overlaps list unless normalize_first is set. This fully discloses the tool's 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?

The description is well-structured and front-loaded with the main action. It contains necessary detail without redundancy, though it could be slightly more concise in the error handling part.

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 parameters, destructive effect, error cases) and no output schema, the description covers all essential aspects: operation, parameter usage, scope, error behavior, and options. It is complete and self-contained.

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 value by explaining that revision_ids target specific w:id values, author is a convenience alternative, and normalize_first is best-effort with no byte-identical guarantee. This context goes 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 clearly states the tool selectively accepts tracked changes by revision id or author, and specifies the scope (document.xml and side-story parts). It also distinguishes behavior for ambiguous overlaps, making the purpose very specific and distinct from sibling tools like accept_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?

The description explains when to use revision_ids vs author, and the normalize_first option for ambiguous overlaps. However, it does not explicitly compare with sibling tool 'accept_changes' to indicate when one should be preferred over the other.

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 that it produces a clean document and returns acceptance stats, but it does not elaborate on irreversible changes, performance implications, or what happens if no changes exist. 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?

Two sentences with no redundant information. The action and key outcomes are front-loaded. Every word contributes to understanding.

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 mentions 'returns acceptance stats' but does not specify what stats (count, success, etc.). The tool is destructive, but reversibility or confirmation steps are not mentioned. Slightly incomplete for a decision-critical operation.

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 parameter 'file_path' described as 'Path to the DOCX or ODT file.' The description adds no further meaning (e.g., file format validation, path examples), so it meets the baseline without exceeding.

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 specific verbs ('Accept all tracked changes') and clearly identifies the resource (document body) and outcome ('clean document with no revision markup'). It distinguishes this tool from siblings like 'has_tracked_changes' (checking) and 'extract_revisions' (extracting).

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 does not provide explicit guidance on when to use this tool versus alternatives. It states the action but lacks context on prerequisites, exclusion criteria, or references to other tools like 'delete_comment' or 'batch_edit'.

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?

The description states the tool creates a tracked-changes output file, but annotations include readOnlyHint=true, which indicates the tool should not modify any state. Creating a file is a state modification, constituting a contradiction. The description does not clarify this inconsistency or disclose other behavioral traits like permissions or error handling.

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 but packed with detail; it front-loads the purpose then segments into mode explanations and format-specific notes. A minor improvement would be to move granular stats to parameter descriptions, but overall it is well-structured.

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 explains input modes and output behavior, but lacks information on the tool's return value (e.g., success message/filename). With no output schema, this is a gap. It also does not clarify handling of conflicting parameters (e.g., providing both original/revised and file_path).

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 parameter descriptions, but the description adds significant value: it explains the two comparison modes, file-type behaviors (e.g., DOCX atom statistics, ODF inline granularity), and default author/engine values. This enriches parameter understanding beyond the schema alone.

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: comparing two documents and producing a tracked-changes output. It explains two modes (standalone and session edit) and supported formats (DOCX, ODF), distinguishing it from siblings like 'extract_revisions' or 'accept_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?

The description implies when to use the tool (for comparing documents) but does not explicitly state when not to use it or mention alternatives among siblings. It contrasts modes but lacks exclusionary guidance, such as 'use extract_revisions for existing tracked changes'.

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?

The description adds that the tool is read-only and does not modify the document, which aligns with annotations (readOnlyHint=true). It also describes the output format and pagination behavior, providing helpful 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?

Two concise sentences: first explains the core function, second adds pagination and read-only status. No wasted words and front-loads key 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?

Given no output schema, the description provides a good overview of the return format. Parameter details are fully covered in schema. It lacks specifics about error handling or file accessibility, but overall sufficient for selection and 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?

Schema description coverage is 100%, and the schema already provides detailed parameter descriptions (offset default 0, limit default 50, max 500). The description only adds that pagination is supported, offering minimal extra 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 it extracts tracked changes as structured JSON with specific details (before/after text, revisions, comments) and supports pagination. This distinguishes it from sibling tools like accept_changes or has_tracked_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?

The description mentions pagination support and read-only nature, which helps in understanding usage context. However, it does not explicitly state when to use this tool versus alternatives (e.g., for retrieving revision data vs. accepting changes).

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 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?

Description adds value beyond annotations by detailing that it returns one entry per heading with text, outline level, source, and paragraph_id, and explains the difference between style-based and heuristic headings. Annotations already declare readOnlyHint=true and destructiveHint=false; description reinforces read-only nature without 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 purpose, no fluff. Every sentence earns its place, efficiently communicating key 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?

Despite lacking an output schema, the description fully explains the return structure and parameter effects. Covers all relevant behavioral aspects for a read-only outline 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?

All three parameters (format, file_path, include_heuristic_headings) are explained in the description with additional context on default values and behavior, complementing the schema coverage of 100%.

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 specifies verb 'Get', resource 'compact structural map of a document's headings', and includes domain 'DOCX only'. Distinguishes from siblings like read_file and replace_text by targeting outlines specifically.

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: 'read the cheap outline first, then scope a targeted read_file/replace_text'. Also states 'DOCX only' and explains the default behavior for style-based vs heuristic headings, providing clear context for agent decision-making.

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?

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 indicate this is not read-only (readOnlyHint=false) and is destructive (destructiveHint=true). The description adds context about ODT positional ID behavior and DOCX tracked changes, which goes beyond annotations. 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 with two sentences. The first sentence covers the main purpose and mechanism. The second sentence adds important warnings and surface behavior. While efficient, it could be improved with line breaks or bullet points for 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?

With 7 parameters, no output schema, and three supported formats, the description covers key constraints (ODT ID shifting, DOCX tracked changes) but leaves parameter semantics vague. It is moderately complete but could include more details on parameter usage and return behavior.

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 43%, with descriptions only for file_path, google_doc_id, and style_source_id. Required parameters (positional_anchor_node_id, new_string, instruction) lack schema descriptions. The description clarifies positional_anchor_node_id via 'anchor paragraph by paragraph id' but does not explain new_string or instruction. The style_source_id parameter is explained in schema, so the description adds limited value here.

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 (Insert), the resource (paragraph), the positioning mechanism (before/after an anchor paragraph by paragraph id), and the supported formats (DOCX, ODT, Google Docs). This distinguishes it from sibling tools like add_comment 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 specifies supported document types and gives a critical warning about ODT paragraph IDs being positional and shifting after insertion, advising re-read before further edits. It also mentions that DOCX insertions emit tracked changes. However, it does not explicitly state when to use this tool versus alternatives, earning a 4 instead of 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?

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds pagination behavior (token limit, has_more, next_offset), which is useful 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?

Two sentences covering core functionality and pagination. Extremely efficient, no 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?

Covers basic purpose and pagination, but doesn't guide on parameter combinations (e.g., format selection, comment rendering). Schema fills many gaps, but description could offer more context for a complex 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 82%, so most parameters are well-documented in the schema. The description briefly mentions offset/limit for pagination, reinforcing schema details but adding limited new 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?

Clearly states 'Read document content' and specifies supported file types (DOCX, ODT, Google Doc). The purpose is distinct from sibling tools, though no explicit differentiation is made.

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 (e.g., get_comments, grep). Does not mention when not to use or contextual 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 already indicate destructiveHint=true. The description adds beyond that by detailing the scope ('sweeps document.xml and supported side-story parts'), the guarantee of leaving other revisions byte-untouched, and the error behavior with a specific error code and structured response. This enriches the agent's understanding of 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?

The description is a single paragraph that fronts the core action and constraints, then details error handling and options. It is dense but efficient. Minor room for improvement by breaking into sentences for readability, but 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 no output schema and 4 parameters, the description covers the core behavior, error states, and the normalize_first escape hatch. It does not describe return values, but incomplete for a mutation tool with no output schema. Acceptable given the detail on error handling.

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 does not add meaning beyond the schema for parameters; it only restates that revision_ids or author can be used, which is already in the schema. No additional syntax, constraints, or examples are provided.

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 ('reject') and resource ('tracked changes'), clearly stating it restores pre-edit state. It explicitly names the sibling 'accept_ai_edits' as symmetric, distinguishing the tool's purpose from similar 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?

The description provides clear context: it is the symmetric counterpart to 'accept_ai_edits', and explains the error handling for ambiguous overlaps with an option to normalize. However, it does not explicitly state when NOT to use this tool or offer alternative tools for different 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?

Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description adds that for DOCX, edits emit native OOXML tracked changes. This is valuable behavioral context. However, it doesn't detail what happens for ODT or Google Docs in terms of revision tracking.

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 three sentences, front-loaded with the main action and supported formats. It is efficient with no unnecessary words, though the 'Surfacing' clause could be more integrated.

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 (7 params, destructive, no output schema), the description covers core purpose, format support, and a key behavioral trait. However, it lacks information on return values, error conditions, or behavior for non-DOCX formats. With no output schema, this leaves 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 43% of parameters have schema descriptions, and the tool description adds little beyond the schema. The 'normalize_first' and 'instruction' parameters are not elaborated in the description. The required 'target_paragraph_id' lacks any description, even though the tool description mentions 'by provider paragraph 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 clearly states the action ('Replace text in a paragraph by provider paragraph id'), specifies supported formats (DOCX, ODT, Google Docs), and emphasizes formatting preservation. This strongly distinguishes it from sibling tools like 'batch_edit' or '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?

The description outlines supported formats but provides no explicit guidance on when to use this tool versus alternatives (e.g., when a simple find/replace is needed vs. batch operations). No 'when not to use' or alternative tool mentions are present.

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, and the description adds context about save report contents (AI revisions, package-level mutations) and Google Docs checkpoint vs snapshot. However, it does not explicitly discuss side effects like file overwriting or the impact of the 'allow_overwrite' parameter, which would enhance 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 somewhat verbose and jumps between format-specific details. It could be more concise and better structured, but it does front-load the main purpose with 'Save document'. Overall adequate but not 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 the complexity of 10 parameters and no output schema, the description is incomplete. It does not explain the return value (save report) in detail, the difference between checkpoint and snapshot for Google Docs in terms of agent expectations, or how to handle tracked changes versus AI revisions. Missing guidance on when to use this tool versus related siblings.

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 schema description coverage at only 40%, the description should compensate but fails to explain most parameters. It mentions save_format indirectly via 'clean and/or tracked changes' but does not describe parameters like allow_overwrite, clean_bookmarks, save_to_local_path, or tracked_save_to_local_path. The parameter semantics are largely missing.

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 'Save document' and elaborates on specific behaviors for DOCX, ODT, and Google Docs, including different save modes (clean/tracked/both) and checkpoint vs snapshot. However, it does not explicitly differentiate from sibling tools like 'export' or 'accept_ai_edits', which have overlapping functions.

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 does not provide guidance on when to use this tool versus alternatives such as 'export' or 'close_file'. There is no mention of prerequisites, when-not to use, or explicit alternatives.

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.