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

The description goes well beyond the annotations: it discloses atomicity ('document is written only if every edit applied'), failure behavior ('file byte-identical and journals nothing'), mode-specific visibility, and receipt/ledger implications. The destructiveHint=true annotation is consistent with the manual edits and tracked/direct rewrite semantics.

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

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

Three tightly written sentences with no filler. The most important behavioral constraint is front-loaded in ALL-CAPS, and each sentence earns its place by adding either atomicity, mode semantics, or the required follow-up step.

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 and the annotations already signal destructive intent, the description covers the remaining high-stakes behavior an agent needs: atomicity, journaling, mode effects, and the commit prerequisite. Nothing essential to calling the tool correctly is missing.

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

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

The actual schema already carries rich per-property descriptions, and the prose adds crucial meaning the enum cannot convey: 'tracked' emits Word revision marks, 'direct' rewrites and is recorded in the ledger alone, and the all-or-nothing semantics apply to the whole batch. That is meaningful value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Apply a batch of edits to the document and record each one in the session's journal.' It clearly differentiates this from siblings like preview_edits and commit_document by naming the commit step as a separate action.

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 clear operational context: edits are all-or-nothing, mode changes the behavior of the edit and what a reviewer sees, and the session must be sealed with commit_document. It doesn't explicitly enumerate exclusions against siblings like preview_edits, but the workflow guidance is strong and actionable.

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?

Despite destructiveHint=true already being in annotations, the description adds substantial context: it destroys the working directory, does not seal a receipt, refuses on non-empty journal unless discard is set, and explains why (throwing away the accountability record). This goes well beyond the annotation.

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 deliver the primary behavior, the guard condition, the escape hatch, and the rationale. There is no filler, and the most important destructive consequence is front-loaded.

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

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

For a destructive, conditional tool with an output schema and annotations, the description covers the action, the destroyed resource, the refusal condition, the override flag, and the reason for the safeguard. An agent has enough to decide when to call it and what will happen.

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 carries the parameter-meaning burden. It clearly explains discard semantics in context. session_id is not elaborated, but its meaning is obvious from the tool name and title, so this is only a minor gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb+object structure: 'End a session and delete its working directory WITHOUT sealing a receipt.' This clearly distinguishes close_document from commit_document, which seals a receipt, and from other sibling operations like open_document or delete_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 provides clear context for when the tool will refuse to operate ('when the journal holds recorded operations') and when to set discard. It does not explicitly name sibling alternatives, but 'WITHOUT sealing a receipt' implies the contrast with commit_document.

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 well beyond the annotations by explaining the gate verdict, refusal condition, force override behavior, recording of the override in the receipt, and the limitation that force cannot bypass an unreadable or unreplayable ledger. This is rich behavioral context that the annotations alone do not convey.

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

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

The description is compact, front-loaded with the core purpose, and every clause earns its place by explaining a meaningful condition or limitation. No filler or repetition of schema/annotation data.

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 the commit gate and the presence of an output schema, the description covers the necessary behavioral conditions, refusal cases, force limitations, and override recording. Nothing essential for correct invocation appears to be missing.

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

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

With 0% schema description coverage, the prose must explain the parameters. It provides detailed semantics for force, including what it can and cannot override. It does not explicitly describe session_id's format or source, but 'End a session' makes its role clear enough for this two-parameter tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly specifies the action: end a session by sealing its journal into a receipt, with a gate condition. It distinguishes the tool from siblings like verify and close_document by describing a unique commit/finalize behavior with refusal semantics.

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 clearly indicates this is the finalization step for a session and explains when a commit will be refused and when force may be used. It does not explicitly contrast it with close_document or other alternatives, but the usage context is strong and unambiguous.

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 richly discloses behaviors beyond annotations: deletion is journaled, tracked mode marks with w:del and is reversible, direct mode removes outright and is only reflected in the ledger, and certain paragraphs cause refusal. Even with destructiveHint=true, this adds real semantic context about side effects and reversibility.

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

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

Dense but efficient: every sentence provides essential operational detail. The main action is front-loaded, followed by addressing, mode semantics, refusal rules, and the follow-up commit step. No filler or repetition.

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 high-risk deletion tool with 8 parameters, the description covers the major failure modes and usage requirements: correct addressing, mode differences, refusal conditions, and the required commit step. An output schema exists for return values, and the description supplies the operational context schema fields cannot.

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 carries the burden. It explains para_id via find_text, the para_index + para_hash pairing and why both are needed, and the mode enum values. However, required parameters like part and session_id are not explained, and note is not addressed, leaving a small gap for an agent.

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 and resource — "Delete one whole paragraph and record it in the session's journal" — and immediately distinguishes what the tool does from related operations like insert_paragraph. It also differentiates tracked vs. direct deletion, making the purpose unambiguous.

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 explicitly explains when to use tracked vs. direct mode, warns against using para_index alone, specifies refusal conditions (section break, unaccepted revision by another author), and tells the agent to seal with commit_document afterward. This is clear, actionable routing guidance with no ambiguity.

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 annotations already establish readOnlyHint and idempotentHint, so the description adds complementary behavioral detail: the tool reports on the working copy as opened rather than disk state, and it guarantees slide order follows <p:sldIdLst> rather than filesystem order. This is meaningful non-obvious behavior beyond what annotations express.

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 dense sentences with no filler. The core purpose is front-loaded, format-specific details are compactly listed, and the verify contrast is placed exactly where it is actionable. Every clause adds useful information.

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

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

With a single obvious parameter, a read-only annotation profile, and an output schema present, the description covers what an agent needs: scope, format-specific behavior, working-copy semantics, and the key sibling distinction. Nothing important is missing for 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?

The schema's only parameter, session_id, has no description (0% coverage). The description does not explicitly define session_id or explain where to obtain it, though the repeated 'session' language makes it reasonably clear the parameter identifies an opened session. This is only partial compensation for the missing 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 opens with a specific verb and resource: 'Report a session document's structure'. It then narrows that scope by naming exactly what structure means — digest coverage and format units for docx, xlsx, pptx. This makes the tool clearly distinguishable from siblings like verify and digest.

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 final sentence directly contrasts this tool with verify: 'Describes the session's working copy as opened; `verify` reports on the file on disk now.' This tells an agent when to choose describe_structure versus a likely alternative. It also relates the tool to digest by framing output as digest coverage, giving useful context for when it would be relevant.

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 and idempotentHint. The description adds behavioral specifics beyond those: output is stable across no-op saves, the digest is used as a receipt key, and no session is needed. This enriches the agent's understanding without contradicting annotations.

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

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

The description is two sentences with no filler. It front-loads the core action, then packs stability semantics, receipt-key role, and session independence into tightly written clauses. Every word 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 purpose, stability, and session-free usage; annotations cover safety and idempotence; an output schema exists for return values. However, the include_parts parameter is left unexplained, leaving a real gap in the information needed to invoke the tool correctly in all cases.

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 never clarifies what the 'document' parameter expects (e.g., document ID vs. content) and says nothing about 'include_parts', which remains completely unexplained in both schema and description. This is a meaningful gap for correct invocation.

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 and resource: 'Compute a document's canonical digest.' It clearly distinguishes the tool from siblings by explaining the digest is stable across no-op Office saves and serves as the key a receipt is stored under, which sets it apart from document editing, search, and export 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?

The description gives clear usage context: use this tool to get a session-free, stable digest for a document, especially when it will be used as a receipt key. It does not explicitly name alternative tools or exclusions, but the stability and session-free notes make when-to-use reasonably 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 carry the safety profile (idempotent, non-destructive, not read-only). The description adds that the emitted artifact is a single self-contained sidecar file, which is useful behavioral context beyond the schema. 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?

A single front-loaded sentence with no filler. The appositive adds use-case context without padding.

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 purpose and high-level behavior are clear, but the tool cannot be confidently invoked without understanding dest and overwrite, and the schema provides no descriptions. The output schema reduces the need to document return values, but the parameter gap remains significant.

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 0% schema description coverage, the description needed to explain the parameters, but it only clarifies 'document' as the receipt source. 'dest' and 'overwrite' receive no explanation, leaving an agent to infer destination behavior and overwrite semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific action ('Write ... out as one self-contained sidecar file') and a clear resource ('this document's receipt'). The use-case framing distinguishes it from siblings like list_receipts and commit_document.

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

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

The description gives clear usage context: attach to a submission, commit to git, or register alongside a DOI. It does not explicitly name excluded alternatives or when-not-to-use conditions, so it stops short of a 5.

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

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

Annotations already provide readOnlyHint and idempotentHint, so the safety profile is covered. The description adds meaningful behavior beyond annotations: case-insensitive matching, scoping to the session's working copy, and per-file-format result address behavior. This gives an agent a realistic sense of what will happen when invoked.

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 dense, purposeful sentences. It front-loads the core search behavior, gives concrete return-address examples, and then adds the crucial working-copy vs. disk distinction. Every clause earns its place with no filler.

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

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

For a read-only search tool, the description is quite complete: it explains scope, matching semantics, result address formats, and relationship to disk state. The output schema covers return structure, so that doesn't need repeating. The only material gap is the lack of guidance around optional parameters like `part` and `max_results`.

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 0% schema description coverage, the description must carry the burden of explaining parameters. It implicitly clarifies `query` and `session_id` through the search behavior and working-copy language, but it never explains `part` or `max_results`. These optional parameters are left to name inference, which is insufficient for an agent selecting values confidently.

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 (case-insensitive substring search) over a defined resource (every text-bearing part the digest covers) and explains the return value as the best address per hit, with concrete examples for docx, pptx, and xlsx. It also differentiates itself from `verify` by noting the working-copy vs. on-disk distinction.

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 clear contextual guidance: results reflect the session's working copy as opened, and `verify` is the tool for the file currently on disk. This tells the agent when this tool is appropriate versus an alternative, though it could be even more explicit about when to prefer find_text over other siblings such as digest.

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?

Goes well beyond the annotations by disclosing tracked-mode w:ins markup, the rejection consequence of removing the whole paragraph, direct-mode ledger accounting, the sibling relationship preserving container boundaries, and the para_hash concurrency guard. This is rich behavioral context the annotations alone do not provide.

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 dense but every sentence contributes needed operational detail: anchor constraints, optional hash semantics, mode consequences, sibling behavior, and commit step. It is front-loaded with the core purpose and then layers the constraints efficiently.

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 9-parameter mutation tool with no schema descriptions, the description covers the essential insertion mechanics thoroughly, but it leaves the required part and author parameters semantically undefined and does not mention note. An agent would still need external knowledge to populate those fields 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?

With 0% schema description coverage, the description must carry the parameter-semantics burden. It explains text, after_para_id, before_para_id, para_hash, and mode well, but leaves required parameters part and author unexplained, and optional note is also absent. session_id is only implied by the session/journal context, not explicitly defined.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific operation and resource: insert a new paragraph beside a named existing paragraph and record it in the session's journal. It also differentiates from related tools by explicitly stating there is deliberately no raw index parameter, making the tool's role 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?

Provides clear, actionable guidance: pass exactly one anchor, use para_hash to guard against stale reads, choose tracked or direct mode deliberately, and seal the session with commit_document. It does not explicitly name sibling alternatives or state when not to use this tool, 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?

Annotations already establish read-only and idempotent behavior; the description adds behavioral detail by promising a flag on the matching receipt and a report of skipped files with reasons, plus the 'as it stands now' qualification that matching uses the document's current state. 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?

A single sentence with no filler, but it is overloaded with three clauses and the phrase 'beside a document' is awkward. The most important action and filtering behavior are front-loaded, but readability could be improved.

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 core behavior (list, flag match, report skips) and the output schema can define return shape, but it omits a definition of receipt/store, the expected document parameter format, and any guidance about why files might be skipped. Adequate for basic invocation, not fully complete.

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

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

Schema coverage is 0%, so the description carries the burden. It relates the single document parameter to the receipt matching and current state, but it never specifies whether document is a path, ID, or content string, leaving a real gap for invocation.

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 concrete action—listing receipts—and adds the key discriminator that exactly one receipt is flagged by matching its digest to the current document, and skipped files are reported by name and reason. It is clear enough to separate from export_receipt or verify, though 'beside a document' is slightly ambiguous.

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 tool's use case is implied by 'List every receipt...' and the mention of skipped files, but the description never explicitly states when to choose this over verify, digest, or export_receipt, nor does it give prerequisites or exclusions.

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

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

The description discloses meaningful side effects beyond annotations: unpacking the document, recording digest and manifest, sweeping expired sessions, and the idempotent resume behavior. This complements idempotentHint=true with concrete details.

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

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

Two dense sentences, front-loaded with the primary purpose and followed by an important idempotency nuance. No filler, every clause adds useful information.

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

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

The output schema exists, so return values are not needed in the description. However, with three parameters, zero schema descriptions, and no explanation of ttl_seconds or keep_baseline, the description is not fully complete for invoking 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 0%, so the description must compensate. It indirectly covers 'document' but says nothing about ttl_seconds or keep_baseline, leaving two parameters semantically unexplained. This is a significant gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb and resource: 'Start an editing session' and describes concrete actions (unpack to disk, record baseline digest and part manifest). It is easily distinguishable from siblings like close_document and commit_document.

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

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

The description communicates clear context: call this to start an editing session, and reopening an unchanged document resumes the live session. It does not explicitly name exclusions or alternatives, but the intended usage moment 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 already declare readOnlyHint and idempotentHint, and the description adds meaning beyond those: it previews against a throwaway copy, includes every session edit already applied, and guarantees a green preview cannot disagree with a subsequent apply. It also discloses that author and mode influence engine refusals, which is a non-obvious 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?

Two sentences, front-loaded with purpose, and every clause earns its place: the throwaway-copy guarantee, the session-state inclusion, and the author/mode rationale. No redundant filler or schema repetition.

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 read-only preview tool with rich annotations and an output schema, the description covers purpose, state assumptions, non-mutation, and a strong consistency guarantee. An agent has what it needs to select and invoke the tool; remaining details like return values are handled by the output schema.

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

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

Schema description coverage is 0%, so the description must compensate. It adds useful rationale for author and mode (engine refusals depend on both), and 'batch of edits' gestures at edits, but it leaves session_id entirely implicit and does not explain the shape or constraints of the edits parameter, which the schema only partially covers via nested fields. This is meaningful but incomplete compensation.

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 opens with a specific verb and object: 'Report what a batch of edits WOULD do' and immediately clarifies it is non-mutating ('writing nothing'). This clearly differentiates it from sibling apply_edits and commit_document without needing to open 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?

The description implies the workflow: run a preview before the 'apply that follows it,' and the throwaway-copy engine guarantees agreement. It does not explicitly name apply_edits as the alternative or state when not to use preview, so it falls short of a 5 on explicit routing.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description is not required to repeat those. It adds useful behavioral context by mentioning 'allowed roots' (access constraints) and 'what this build can and cannot do' (capability boundaries), which go beyond what annotations express. There is no contradiction with the read-only hints.

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 compact phrase with no filler, naming three distinct content areas in sequence. It is efficiently front-loaded with the core subject ('Versions') and then scopes outward to roots and capabilities. It loses one point only for being a noun phrase rather than a complete instruction, which slightly reduces readability for an agent scanning quickly.

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 zero-parameter, read-only, idempotent capability-discovery tool, the description together with the output schema is complete. The agent knows exactly what kind of information to expect and that the call is safe. No prerequisites, side effects, or error conditions are relevant given the annotations. Nothing necessary for correct invocation is missing.

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

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

The input schema has zero parameters and 100% schema description coverage, so there is nothing for the description to clarify. Per the calibration baseline, zero-parameter tools receive a 4 unless the description adds exceptional value, which is not needed here. The description's content list (versions, roots, capabilities) appropriately orients the agent toward what the return payload will cover.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names concrete subjects—versions, allowed roots, and build capabilities—so the tool's purpose is clear even without an explicit verb. It also distinguishes server_info from sibling document-editing tools by focusing on environment/build facts rather than document operations. It stops short of a full 5 because there is no explicit verb phrase like 'Get server information', though the intent is unambiguous.

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 this tool is for discovering build versions, root restrictions, and capability limits, which is enough for an agent to infer when to call it. It does not explicitly state when to prefer it over siblings or when to avoid it, but the sibling names are all document operations, making the intended use reasonably clear. No explicit exclusions or alternative routing are given.

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

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

Annotations already establish read-only and idempotent behavior; the description adds useful behavioral detail by enumerating verified, unknown, and failed outcomes and by noting the check is stateless and CI-compatible. This exceeds the minimum while not going into every edge case (e.g., how `original` affects verification).

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-load the purpose and outcome contract, with no filler or repetition of annotation details. Every clause contributes (outcomes, digest matching, sessionlessness, CI equivalence).

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 and annotations, the description does not need to document return values or safety, and it covers the core outcome contract well. However, with 0% schema coverage and an unexplained `original` parameter, the full calling contract is not quite 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 input schema has 0% description coverage, so the description must compensate for the parameters, but it only implies `document` and `receipt` and never explains `original` at all. An agent cannot reliably distinguish the role of `original` from 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 opens with a specific verb and object (“Check a document against its receipt”) and then clarifies the three distinct outcomes, so an agent knows what the tool does. It does not explicitly name or contrast sibling tools, so it misses the differentiator bar for a 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 statement “Needs no session — the same check runs in CI via `ooxml-ledger verify`” gives concrete context for when the tool is appropriate and signals it can be used in automated pipelines. It does not name alternatives or state when not to use it, so it stops short of full guidance.

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