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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses atomic writes, re-reading of the file, and returns of doc_hash plus warnings about unmodeled features. This is valuable detail. It does not mention reversibility or concurrency checks, but the atomic write and re-read give a solid sense of safe 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, highly efficient. The main purpose is front-loaded, followed by key behavioral notes. No fluff or redundant phrasing. Every sentence contributes.

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?

An output schema exists, so return values are covered separately. The description explains the core behavior and output (doc_hash, warnings), but omits details like the significance of doc_hash as a parameter, potential errors, or behavior when no changes are staged. Given the moderate complexity (3 params, 1 required), it is adequate but has clear 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 description coverage is 0%, so the description must explain parameters. It implicitly explains change_ids ('selected change ids') but does not clarify the role of doc_hash (likely an optimistic concurrency token) or path (though path is self-evident). The description adds minimal value beyond the schema for parameters, leaving doc_hash underspecified.

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: 'Commit staged changes to the file' with an option for all or selected change ids. It implies the file is specified by path (required param). It is distinct from the sibling 'discard_changes' which does the opposite, though it doesn't explicitly name the alternative. Purpose is clear and specific.

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 the tool is for finalizing changes that have been staged (presumably via get_changes or propose_* tools) but does not explicitly state when to use it versus alternatives like discard_changes. There is no mention of prerequisites or a typical workflow. Usage context is inferable from siblings but not spelled out.

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 no annotations provided, the description carries the full burden of behavioral disclosure. It states that it drops staged changes, implying a destructive action, but it does not warn about irreversibility, side effects on the document, or any prerequisites. The description adds little beyond the tool's name and basic action, which is insufficient for a mutation tool.

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, front-loaded sentence with no fluff. It states the core capability and a key parameter detail efficiently. However, it is slightly too brief to be fully helpful, though the structure is clean and wastes no 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?

Given that this is a destructive tool with no annotations and very low schema description coverage, the description is incomplete. It does not cover when to use it, side effects, or parameter details. The presence of an output schema mitigates return-value concerns, but the overall context is lacking for safe and correct usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for missing parameter documentation. It mentions 'specific change ids' but does not explain the format of change_ids, what path refers to, or how they relate. It also fails to clarify that change_ids is optional or its default behavior. The description adds minimal value for the two parameters.

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 'drop' and clearly identifies the resource 'staged changes'. It also clarifies that it can handle all changes or specific ones via 'change ids', which distinguishes it from siblings like apply_changes or propose_* tools. The meaning is unambiguous and the scope is well-defined.

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 explicitly state when to use this tool versus alternatives like apply_changes or propose_* tools. It implies the action but lacks any contextual guidance, such as 'use this to revert proposed changes' or 'do not use this if you want to keep the changes'. The usage context is left entirely 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?

With no annotations provided, the description carries the full burden. It discloses that conversions go through a normalized model, explains how each direction works ('builds a fresh Word file' vs 'serializes parsed blocks'), and states error behavior ('raise a clear export_error listing supported conversions'). This goes beyond a simple 'convert' statement and gives the agent a realistic expectation 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 two sentences, front-loaded with the core purpose. Every sentence earns its place—the second sentence adds valuable implementation detail. No fluff or redundant phrasing, making it efficient and readable.

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?

An output schema exists, so the return format is presumably covered. However, the description leaves key parameters undefined and does not specify default behaviors (e.g., what happens if output_path is omitted, whether include_comments affects both directions). Given the tool's moderate complexity and the presence of five parameters, these gaps prevent it from being 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 description coverage is 0%, so the description must compensate. It only references target_format indirectly ('markdown'|'docx'), but does not explain the roles of 'path', 'title', 'output_path', or 'include_comments'. The parameter names might hint at their function, but the description offers no elaboration. This is a significant gap for an agent to call the tool 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 starts with a clear verb and resource: 'Convert the document to another supported format'. It explicitly names the two supported formats, distinguishing this from all sibling tools which are read, search, or edit operations. The unique purpose is unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

While the description does not explicitly contrast with alternatives, the sibling list confirms no other tool handles format conversion. The stated purpose makes the usage context evident. It also warns about unsupported pairs, giving an implicit hint that this is the only conversion tool. No explicit when-not guidance, but it's not needed given the clear distinction.

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?

No annotations are supplied, so the description carries the full burden. It discloses the return format (offsets + snippet), the skip of tables, and the direct coupling to propose_replace_text. However, it does not mention regex behavior, case-sensitivity defaults, doc_hash validation semantics, or scope_element_id scoping, which are meaningful behavioral traits for a search tool with zero annotation coverage.

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 zero filler. The core purpose is front-loaded, the return format follows, and the key limitation is last. Every sentence earns its place.

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?

An output schema exists, so return-value details are covered by structured data, and the description adds workflow context plus the tables caveat. But with 6 parameters, no annotations, and near-zero schema coverage, the description leaves doc_hash and scope_element_id behavior unexplained. Completeness is adequate for a simple search but thin for the parameter surface.

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 0% across 6 parameters, and the description compensates little: it explains the output semantics and mentions 'propose_replace_text' but never describes the input parameters. is_regex and case_sensitive are only implied by their names; doc_hash and scope_element_id are completely unexplained. With zero coverage, the description should have done far more to clarify parameter behavior.

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 ('Find exact occurrences of text inside document blocks'), then sharpens the scope with 'inside document blocks' and 'Tables are skipped (cell-level search not supported)'. This clearly distinguishes it from siblings like read_document and get_outline, so an agent can tell what it targets 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?

It gives concrete workflow guidance: 'feed these offsets directly into propose_replace_text', which tells the agent how the output plugs into a downstream tool. It also flags the tables limitation. It does not explicitly state when-not-to-use versus read_document or propose_insert_block, but the workflow hint provides clear context for the intended search-then-replace flow.

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 no annotations provided, the description carries the burden of behavioral disclosure. It discloses what each change type will look like: 'Replace changes carry unified diffs; inserts/deletes/comments show their content.' This gives the agent a concrete expectation of the output. It does not mention read-only status or side effects, but the verb 'review' and the separation from apply/discard tools imply a non-mutating operation. The description adds real value beyond just 'get 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 two sentences, with the core purpose front-loaded in the first sentence and supporting detail (diff types, selective apply) in the second. There is no redundancy or fluff; every sentence earns its place. It is exceptionally efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists (as indicated by context signals), the description does not need to explain return values. It covers the tool's scope, the nature of the diffs, and how to proceed with apply_changes. The only missing piece is clarification of the 'path' parameter, but that is already addressed under parameter semantics. The tool is a straightforward review step in a larger workflow, and the description is sufficiently complete for an agent to use it 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?

The input schema has only one required parameter, 'path', and the schema description coverage is 0%. The description does not mention 'path' at all, leaving the agent to infer its meaning from the tool name and context. This is a significant gap for a single-parameter tool, as the description should clarify what path refers to (e.g., document, workspace).

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 clear verb and resource: 'Review all staged changes with diffs before committing.' It specifies the scope ('all staged changes'), what's included (diffs), and the context (before committing). This distinguishes it from apply_changes (which applies) and discard_changes (which discards), and the mention of replace, inserts, deletes, and comments adds specificity beyond a generic 'get 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 usage context: 'before committing' indicates this is a review step, and 'Apply selectively with apply_changes(change_ids=[...])' explicitly names the alternative for the next action. It does not list when not to use or compare against other siblings, but the flow from review to apply is clearly sketched, providing adequate 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?

Since no annotations are provided, the description carries the full burden of disclosing behavior. It does state that the tool handles native DOCX comments and returns empty for Markdown, which is useful behavioral context. However, it does not mention whether the operation is read-only, if it requires specific permissions, or any side effects. For a listing operation, the read-only nature is implied but not explicitly declared.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is concise and front-loaded: it states the core purpose immediately, then provides additional detail on comment fields and the Markdown caveat in just two short paragraphs. Every sentence adds value with no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

While an output schema exists (so return structure is covered), the description fails to clarify the essential parameters, which are also undocumented. Additionally, there is no guidance on how to identify the document (path vs. hash) or any prerequisites. For a tool with two parameters and no annotation support, this is insufficient for confident invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% description coverage, meaning the parameters 'path' and 'doc_hash' are not explained in the schema. The description also does not explain these parameters at all. It lacks any semantics regarding what 'path' refers to (file path? document ID?) or how 'doc_hash' is used. This is a critical gap for agent correctness.

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 operation ('List comments') and the resource ('anchored in the document'), with a precise qualifier ('native DOCX comments'). It distinguishes this from other tools by noting Markdown returns an empty list, which prevents ambiguity with sibling tools like get_changes or get_outline.

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 no explicit 'when to use' guidance or comparison with alternatives. It only mentions that Markdown yields an empty list, which is more of a behavioral caveat than usage direction. Without mention of siblings like get_changes or read_document, an agent may not know when this tool is appropriate.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does disclose the return structure (flat entries plus nested tree), but it does not explicitly state whether the operation is read-only, what happens if the path is invalid, or whether there are any side effects. The name 'get' implies non-mutating, but this is not stated.

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 succinct and front-loaded. The main purpose is stated in the first line, and the additional detail about the return format and usage is directly relevant. No extraneous 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?

With no annotations and 0% schema coverage, the description falls short in explaining parameter semantics and error behavior. However, the presence of an output schema likely covers return format, and the tool's simplicity (read-only outline retrieval) reduces the need for extensive context. Still, the missing parameter explanation makes it incomplete.

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 description coverage is 0%, so the description must compensate by explaining the parameters. It does not mention 'path' or 'doc_hash' at all. The agent must guess that 'path' identifies the document and that 'doc_hash' is possibly a version hash. This is a significant gap given the lack of schema documentation.

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 states a specific verb ('Get') and a well-defined resource ('heading outline of a document'), which is clearly distinct from sibling tools like read_document (full content), find_text (search), or get_comments (comments). No ambiguity exists about what this tool does.

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 a concrete use case ('Use heading ids to read sections or anchor edits') which helps an agent understand when to invoke it. However, it does not explicitly contrast with alternatives or state when not to use it, so it falls 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?

No annotations are provided, so the description carries the full burden. It states what the tool does but does not explicitly mention that it is read-only or side-effect-free. However, as a listing operation, this is largely implicit. It also does not describe the output structure, but the existence of an output schema mitigates that. The description is adequate but lacks explicit behavioral detail.

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, well-formed sentence that contains no filler or redundant words. 'List registered format backends and their file extensions' is succinct and front-loads the core function. There is zero waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given zero parameters and the presence of an output schema, the description is sufficient for an agent to understand the tool's purpose and invoke it correctly. It specifies the output informally and the output schema can handle formal structure. No additional context about errors or ordering is needed for a simple list 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?

The tool has zero parameters, so per the rubric the baseline is 4. The empty input schema and 100% schema description coverage mean there is nothing to explain. The description accurately reflects that no arguments are needed, and the tool's purpose is fully self-contained.

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 ('List') and the resource ('registered format backends') and specifies what is included ('their file extensions'). It is unambiguous and distinct from the sibling tools, which focus on document operations or export. The verb and object are specific, meeting the highest bar.

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 no guidance on when to use this tool versus alternatives. It does not mention any context, prerequisites, or relationships to sibling tools like export_document. An agent would have to infer that this might be useful before exporting, but the description says nothing.

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 no annotations, the description must carry the full behavioral burden. It discloses that DOCX creates a real Word comment, Markdown only stores in-session until process exit, and the tool result explicitly states the limitation. It also mentions the quote constraint. This is transparent, though it doesn't clarify whether 'stage' means the change is not immediately applied (e.g., requiring apply_changes) or cover all 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 well-structured: a clear purpose statement followed by format-specific details and a constraint. It is concise and every sentence provides value, though it could be slightly more compact by merging some lines. Overall, it's efficient and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description explains format differences and a constraint, but it doesn't explain what 'stage' means in the workflow (e.g., whether it requires apply_changes), nor does it document most parameters. With 8 parameters, an output schema, and no annotations, the description is insufficient for an agent to correctly fill all required fields without additional context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for the 8 undocumented parameters. It only explains the constraint on quote (must appear inside the anchor element) and implies the role of anchor_id. It does not explain start, end, doc_hash, author, or path, leaving most parameters ambiguous. This is a significant gap for a tool with this many parameters.

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 that the tool stages adding a comment anchored to an element, and it distinguishes behavior across DOCX (real Word comment) and Markdown (session-only). It mentions get_comments as a sibling for surfacing comments, which provides some differentiation. However, it doesn't explicitly contrast with other propose_* tools like propose_insert_block, so it's not a perfect 5.

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 format-specific guidance (DOCX vs Markdown) and notes the Markdown limitation, which helps the agent decide when to use the tool. It also hints that get_comments is the way to view Markdown comments. However, it doesn't explicitly state when not to use this tool or provide alternatives for different operations, leaving some inference to the agent.

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 word 'Stage' indicates the operation is not immediate and likely part of a draft workflow, which is a valuable behavioral disclosure given that annotations are absent. However, it does not explain the consequences of staging (e.g., that the deletion won't take effect until applied), any side effects on child elements, or whether the action is reversible. These gaps leave the agent uncertain about the tool's full 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 a single, tight sentence that front-loads the core action and resource. It includes only essential details (block types) and avoids redundancy. Every word adds value, making it highly efficient for an agent to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite an output schema, the description lacks crucial context for a staging mutation: how the staged deletion interacts with child blocks, whether the deletion is part of a change set that must be applied, and how errors or conflicts are surfaced. Combined with no annotations and undocumented parameters, the description is not sufficient for an agent to use the tool confidently in varied 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?

With schema description coverage at 0%, the description must compensate by explaining each parameter's meaning. It implicitly clarifies that 'element_id' identifies a block of the listed types, but it provides no explanation for 'path' or 'doc_hash' and their roles in locating or validating the block. Two of three parameters remain undocumented, leaving the agent to guess.

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 a specific action ('Stage deleting') applied to a specific resource ('one whole block') and enumerates the valid block types (heading, paragraph, item or table). This distinguishes it from sibling tools like propose_replace_text and propose_insert_block, which perform different operations on blocks.

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 no guidance on when to use this tool versus the alternatives. There is no mention of scenarios that favor deletion over replacement or insertion, nor any conditions where this tool should not be used (e.g., when only part of a block should be deleted). Relying on inference from the tool name alone is insufficient.

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 no annotations provided, the description must fully disclose behavioral traits. The name 'propose_' and the opening word 'Stage' hint that this is a proposal, not a direct mutation, but the description never clarifies what staging means (e.g., that changes are not applied until apply_changes is called, or that it is non-destructive). It also does not mention permissions, reversibility, or concurrency checks (despite having a doc_hash param). The behavioral information is thin and leaves critical operational details implicit.

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 compact — three sentences — and front-loads the core action in the first sentence. The parameter breakdown is efficient and read naturally. It avoids redundancy and focuses on essential distinctions. Minor redundancy exists in repeating 'position' and 'kind' definitions, but overall it is well-structured and to the point.

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 tool is a 'propose' operation within a change-management workflow, as evidenced by siblings like apply_changes, discard_changes, and get_changes. The description does not explain how this proposed insertion integrates with that workflow (e.g., what the return value is, how to confirm it, or whether it conflicts with an existing proposal). An output schema exists but is not referenced, and the description does not mention the doc_hash's role in optimistic concurrency. Critical workflow context is missing for safe and correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must explain all parameters. It explicitly documents the 'position' and 'kind' values, and indirectly explains the anchor_id via positioning. However, it does not explain 'path', 'text', 'level', or 'doc_hash' — even though 'level' is noted as being set for headings, the description does not state that level applies to 'heading' kind or that text is the content. The coverage is incomplete for a tool with 7 parameters.

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 states a specific verb ('Stage inserting') and resource ('new block') with clear positioning relative to an anchor element. It explicitly enumerates the supported block kinds and positions ('before'/'after'), and distinguishes itself from sibling tools that replace or delete content by the verb 'insert'. The scope is unambiguous and 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?

The description provides clear usage context: it covers insert-before, insert-after, and append (via anchoring on the last element with position='after'). It directly tells the agent how to achieve append without a dedicated append tool. However, it does not explicitly state when not to use this tool or mention alternatives, though the sibling set makes that inference straightforward. The guidance is practical and adequate.

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 no annotations provided, the description carries full behavioral burden. It discloses that nothing is written until 'apply_changes,' reveals the staging behavior ('staged change includes before/after previews'), and states a clear limitation (table cells not supported). This is sufficient for a non-destructive staging operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is three concise sentences with no fluff. The core purpose is front-loaded, followed by essential offset provenance and a critical limitation. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the essential operational details: staging behavior, previews, offset source, and unsupported case. Since an output schema exists, return format need not be described. The only gap is the unexplained role of 'path' and 'doc_hash,' but overall it is sufficiently complete for an agent to invoke 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?

The schema has 0% description coverage, so the description must compensate. It clarifies start/end as offsets and text as replacement content, and implies element_id is the block. However, it does not explain 'path' or 'doc_hash,' which remain semantically ambiguous. The added value is partial.

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: 'Stage replacing character range [start:end) inside one block.' It identifies the specific verb (stage replace), the resource (one block), and the exact range semantics. It naturally distinguishes from siblings like propose_insert_block and propose_delete_block by specifying 'replacing'.

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 concrete usage context: offsets derive from 'find_text or read_document,' and it explicitly notes that table cells are unsupported with a suggested alternative ('delete/re-insert the table'). However, it does not explicitly compare against insertion or deletion siblings, leaving some inference to the agent.

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 no annotations, the description carries the behavioral burden. It discloses the output format (headings, paragraphs, list items, tables with stable IDs), the behavior of listing unmodeled_features, and the use of doc_hash for change detection. It implies read-only but does not explicitly state it; however, the presence of these details demonstrates transparency beyond a simple read action.

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 with zero waste. The main purpose is stated first, followed by actionable tips. Every sentence adds value, and the structure is front-loaded 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?

The presence of an output schema shifts the burden of return-value documentation to schema, which is appropriate. The description adds key context: usage guidance for parameters, the nature of returned blocks, and the list of unmodeled features. Minor gaps remain (e.g., include_spans semantics, error behavior), but overall it is sufficient for an agent to call 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?

The schema has 0% description coverage, so the description must compensate. It explains section_id and doc_hash meaningfully, but path and include_spans are left to their names. This partial coverage is a moderate contribution, but not complete for all parameters.

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 states a specific verb ('Read'), resource ('Markdown or DOCX document'), and output ('structured blocks'). It differentiates the tool's purpose from siblings by emphasizing structured representation and stable IDs, which is distinct from outline-only or search tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance is given for using section_id ('Prefer section_id over reading whole documents') and doc_hash ('Pass doc_hash from a previous call to detect external modifications'). While it does not explicitly compare with siblings, the usage tips provide clear context for how to invoke the tool effectively.

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