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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint=false), and the description confirms 'Read-only' plus adds what the anchor captures (quoted text, context window, paragraph number and fingerprint). It also discloses two specific failure conditions (STALE_ADDRESS, SCHEMA_INVALID), which is useful beyond the annotations, though return/persistence behavior is only lightly implied.

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

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

Front-loads the core purpose before the format details and alternatives, and every clause carries information. It is dense but not padded, using semicolons to pack parallel facts 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?

An output schema exists, so return values need not be explained. The description covers purpose, input formats, alternatives, read-only nature, and error codes, leaving nothing an agent needs to call it correctly unaddressed.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters, including the `at` format examples and the context default/max. The description largely restates these (context default 32, max 200; range vs whole-paragraph vs sentence forms) with no additional syntax beyond the schema, so it lands at the baseline.

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

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

States a specific verb and resource ('Make an anchor for a passage') and immediately explains purpose ('so it can be found again after edits shift or change addresses'). It clearly distinguishes itself from the sibling anchor_resolve by describing the create-vs-find relationship.

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 instructs when to use it ('bookmark passages you will come back to') and names both alternatives by function: find them later with anchor.resolve, and text.find searches for any text instead. The routing decision is fully specified.

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 cover read-only/idempotent, and the description goes well beyond them: the 0.80 fuzzy threshold, the failure modes ANCHOR_NOT_FOUND and ANCHOR_AMBIGUOUS (listing up to 5 tied candidates), and the strictest-level resolution rule. This is exactly the behavioral detail an agent needs before invoking a fuzzy matcher.

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

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

Purpose and return shape are front-loaded, and almost every sentence carries load (thresholds, error codes, ladder semantics). The prose is dense and dash-heavy, making a few sentences harder to parse than necessary, which keeps it just below the top mark.

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 complex resolver with nested anchor input, two enums and fuzzy behavior, the description covers inputs, default modes, fallback thresholds, and both failure paths. An output schema exists, so return-value documentation is correctly left out.

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 schema already documents all four parameters and both enums, establishing a baseline of 3. The description adds real value on top by stating the 0.80 fallback threshold for mode=best and explicitly disambiguating the reply's `match_level` from the `match` kind, which the schema does not spell out as clearly.

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?

Specific verb (find/resolve) plus resource (an anchor's passage) and states exactly what is returned: current range, a 0-1 score, and the match kind. It also distinguishes itself from siblings by naming anchor.create (input source) and doc.diff (address mapping between files).

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

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

Gives the triggering condition ('re-address a passage after edits'), the exact alternative with a different job ('doc.diff maps addresses between two files instead'), and the accepted input forms (full anchor.create object or minimal {exact, prefix, suffix}).

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 annotations only covering the safety profile, the description adds substantial behavioral detail: tracked insertions, a hidden bookmark, backup plus undoability via history.undo, dry_run previewing, the expect.sha256 write guard, and a specific UNSUPPORTED_CONTENT failure for text-box paragraphs. This is far beyond what annotations 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?

Front-loaded with the core action, then semicolon-delimited supporting facts. It is dense but every clause carries information; slightly packed/run-on phrasing keeps it from a 5.

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 need not be spelled out, yet the description still notes it returns the caption's address. Combined with undo/safety, dry_run, and error disclosure, an agent has everything needed to call this write 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 coverage is already 100%, so the baseline is 3. The description adds real meaning on top: a concrete worked example for `text` ('label Table, text "Results" gives "Table 3 Results"'), the position default rule tied to label, and how expect.sha256 behaves when a file changed.

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

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

States a specific verb+resource ('Add a numbered caption next to a body paragraph') and immediately scopes it to tables, figures, or equations. It names related siblings (xref.add, field.update) so an agent can distinguish this insertion tool from cross-reference or field-update 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 operating context: position defaults per label type, that xref.add points at the created bookmark, and that field.update renumbers later. It does not state explicit when-not conditions or name a sibling to prefer, so it stops short of full routing 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 only declare the safety profile; the description goes well beyond them by disclosing the backup-first behavior, dry_run preview, expect.sha256 guard with its DOC_CHANGED_ON_DISK failure, history.undo logging, and the live-window side effect. This is exactly the mutation context an agent needs.

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

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

Front-loaded with the core action and the `at` syntax, then engine/guard behavior. Dense but every clause carries information; only the long example list for `at` borders on over-length.

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

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

For an 8-param mutation tool with nested expect, dual engines and an output schema, the description covers invocation formats, guards, side effects and the return value. An agent has everything needed to call 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?

Schema coverage is already 100%, so baseline is 3, but the description adds real format semantics: the three `at` forms with concrete examples, the newline-starts-a-new-paragraph rule for `text`, and the DOC_CONTROL_AUTHOR author default — none of which the terse schema descriptions spell out.

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?

Specific verb+resource ('Add one comment on a range') with the target scoping made explicit, and it is clearly distinguishable from comment_list, comment_reply and comment.resolve. The 'one comment' vs doc.batch split is stated outright.

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?

Names alternatives and the conditions that select them: doc.batch for several comments, comment.reply/comment.resolve for bundled all-or-nothing work, and live.open required before engine live. No explicit 'when not to use', but the routing guidance is concrete.

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, so the safety profile is covered. The description adds real behavioral context beyond that: comments include those in notes and headers, text is clipped at 1,000 characters, and responses are paged with a ~8,000-byte cap and `cursor` continuation. The only repetition is the 'Read-only' statement, which annotations already supply.

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

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

Purpose and return shape are front-loaded, and nearly every clause carries information (ordering, clipping, filters, paging, sibling routing). It reads as one long run-on sentence, so structure is dense rather than broken into scannable units.

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 list tool with an output schema present and 100% schema coverage, the description covers the remaining agent-critical facts: ordering semantics, content clipping, paging continuation, and where to go next for related operations. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds matching semantics the schema leaves implicit: `author` is an exact match, and `cursor` must be set to the previous reply's `next` value. The `resolved` true/false explanation largely restates 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 opening clause gives a specific verb and resource ('List the comments') plus the ordering model ('thread order: each root comment, then its replies') and the exact fields returned. It explicitly separates itself from revision.list for tracked changes, so an agent can distinguish it from siblings 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 states the filters (`resolved` true/false, `author` exact) and routes the agent onward: use the returned ids to reply/resolve via doc.batch (comment.reply, comment.resolve), and use revision.list instead for tracked changes. The when-not condition (tracked changes) and the alternative are named explicitly.

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

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

Annotations only declare the safe-mutation profile (readOnly=false, destructive=false), while the description carries all the real load: backup-then-write, dry_run preview, expect.sha256 refusal (DOC_CHANGED_ON_DISK), undo semantics, BATCH_CONFLICT/STALE_ADDRESS errors, and detailed tracked:false behavior including UNSUPPORTED_CONTENT refusals and out-of-order-undo limits. Exceptionally rich and non-contradictory.

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?

One dense paragraph that front-loads the core purpose, then families, then engine/tracked nuances. Every clause carries information (error codes, engine limits, undo rules), though the compression makes it heavy reading for a first-pass selection.

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 complex 8-parameter, nested, multi-op write tool with an output schema already present, the description covers the engine choice, tracking semantics, write guard, backup/undo, and refusal modes. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so parameters are already documented, but the description adds value beyond the schema: the concrete address form ('p3#a1b2c3d4:10-15'), the family-grouping rule, and the tracked:false consequences that the schema only names. It stops short of fully explaining every op's fields (deferring to server.help), so it sits above the 3 baseline but not maximal.

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

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

States a specific verb and resource ('apply several edits in one verified write, as tracked changes, all or nothing') and enumerates the exact op families it covers. This lets an agent distinguish it from the many single-op siblings (text_replace, para_delete, style_update, revision_accept, comment_add) without opening any schema.

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

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

Gives the key selection rule ('One family per batch') plus preview/guard behavior and the live-engine restriction to comment.add/text.replace/para.insert. It implies the batch-vs-single-op choice rather than stating it outright ('use this when you have multiple edits, otherwise the single-op tools'), so it falls just short of explicit when/when-not 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?

With annotations present, it adds substantial behavioral context beyond them: the output must not already exist, input files are never modified, defaults (author Claude, date now), and the verify-or-restore outcome (VERIFY_FAILED_RESTORED). These are exactly the side-effect and failure-mode details an agent needs 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?

Front-loads the core action and packs defaults, verification, and the alternative into a dense but single-purpose block. Slightly long with stacked parentheticals, but nearly every clause 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 explanation is optional, yet the description summarizes it (path, hash, per-kind counts, revision count). Combined with the side-effect and failure semantics, an agent has everything needed to invoke 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?

Schema coverage is 100%, so the baseline is 3, but the description adds a genuinely new default ('date ... default now') and reinforces the must-not-exist constraint on `output`. It mostly mirrors the schema, hence not a 5.

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

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

States a specific verb and artifact: 'Write a redline: a new .docx at `output` ... with every difference from `old` as a tracked change.' It explicitly distinguishes itself from the sibling doc.diff, so an agent can tell the two apart without opening a schema.

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

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

Names the alternative and the condition that selects it: 'Use doc.diff for the alignment as data without writing a file.' It also frames the human workflow (writer reviews and accepts/rejects in Word), making the intended use 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?

Annotations already declare readOnlyHint/idempotentHint/openWorldHint=false, so the safety profile is covered, but the description adds genuinely new behavior: paging at ~8,000 bytes with limit and cursor carried forward from the previous reply's `next`, and that deleted paragraphs map to null. A minor gap is that it doesn't describe error behavior on missing/mismatched files.

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

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

Front-loaded with the core verb+resource, then alternatives, then pagination mechanics. No filler sentences, though the single dense paragraph packs several distinct ideas (output, alternatives, siblings, pagination) that could be split for faster scanning.

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 an output schema present, return shape need not be spelled out, yet the description still explains the address map and null-for-deleted semantics. Combined with read-only disclosure, sibling routing, and pagination rules, an agent has everything needed to call this 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 coverage is 100% and the schema documents each parameter, so the baseline is 3. The description still adds value by tying limit+cursor together as a pagination mechanism ('the `next` of the previous reply') and explaining collapse_runs as folding shifted-unchanged runs into one record, which the schema only states in one line.

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

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

States a specific verb and resource ('Align the paragraphs of two versions') and enumerates the exact change categories (unchanged, modified, moved, split, merged, inserted, deleted) plus the old-to-new address map. It also names the sibling doc.compare and how it differs, so an agent can select correctly without opening schemas.

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

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

Explicitly gives the two intended uses ('carry addresses read from an older version over to the current one, or to see what changed') and routes the alternative case to doc.compare ('writes the same differences as a redline .docx instead'). It also notes when to reach for collapse_runs.

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, but the description adds substantial context beyond them: the lock-file detection for an open document, the staleness-check contract around sha256, and the specific error outcomes (DOC_NOT_FOUND, NOT_A_DOCX). This is far richer than the safety profile alone.

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 dense paragraph, front-loaded with the 'cheap first look' framing followed by the payload contents and routing hints. Nearly every clause carries information, though the sha256/expect.sha256 aside is a touch embedded and could be tighter.

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 an output schema present the description needn't explain returns, yet it still previews the envelope (doc paragraph count), states the error codes, and routes to alternatives. Nothing an agent needs to call it correctly is missing.

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

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

There is one parameter and schema description coverage is 100%, so the schema already fully documents 'doc' as the path to the .docx. The description adds no syntax or format detail beyond that. Per the baseline rule for high coverage, a 3 is appropriate.

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

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

States a specific verb+resource ('Cheap first look at a file') and enumerates exactly what it returns: size, sha256, core properties, Track Changes state, lock file, and existing parts. It explicitly distinguishes itself from doc.stats and doc.outline, so an agent can tell it apart from those siblings without opening any 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?

Names the alternatives explicitly ('Use doc.stats for word, heading and revision counts, doc.outline for the headings') and frames itself as the cheap first-pass call. It also describes the intended downstream workflow (pass sha256 as expect.sha256 so a later write is refused if the file changed), giving concrete when-to-use 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?

Richly discloses side effects that annotations do not cover: backup location (.doc-control/<file name>/), retention policy (20 backups or 30 days kept), undo-log behavior, and that the document is not modified. With destructiveHint=false and readOnlyHint=false, the description meaningfully explains what the tool actually does behind the scenes.

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

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

Dense but front-loaded: starts with the core action, parenthetically provides backup mechanics, then the adoption edge case, then the return shape. No fluff; every clause carries 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 an output schema exists, the description still helpfully names what is returned (backup path, log entry, store folder) and explains the adoption route. For a single-param tool with output schema and annotations, this is thorough.

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

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

Schema coverage is 100% and the single param 'doc' is documented as 'Path to the .docx.' The description's mention of orphaned stores and adoptable adds contextual meaning about output, though not about the parameter itself.

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

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

States a specific verb (start a session) on a specific resource (a document), and explicitly clarifies the counterintuitive behavior: 'the document itself is not changed' and 'Call it once before editing'. This distinguishes it from doc_batch, doc_compare, and live_open 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?

Provides clear timing guidance ('Call it once before editing') and conditional logic ('If the document has no history yet...'), routing the agent to history.adopt. It stops short of explicitly naming when NOT to use it vs. siblings like live_open or doc_diff.

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 readOnly/idempotent annotations by disclosing paging mechanics (about 8,000 bytes per reply, limit up to 1,000, continue with `cursor` set to `next`). It also names what each item contains (address, level, style, text), giving concrete behavioral context.

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

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

Front-loads the core purpose and is dense but mostly earns its words. It is a little packed with clauses, but no sentence is pure filler.

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

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

With an output schema present, the description is not obligated to describe returns, and it still covers filtering, story selection, paging/continuation, and alternatives. An agent has everything needed to invoke 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?

Schema coverage is 100% (baseline 3), but the description adds real semantic value: "max_level 2 keeps levels 1-2" clarifies the parameter's effect and stories ["body","notes"] is shown with example values and behavior. It stops short of explaining the `headers` story option present in the schema.

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

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

States a specific verb ("List") and resource ("headings"), with scope (levels 1-9, by style or outline level, in document order) and the returned fields. It effectively distinguishes itself from siblings doc.segment, para.list, and para.get by name.

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

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

Explicitly routes the agent to alternatives: doc.segment for chapters not styled as headings, para.list for every paragraph, para.get to read one heading in full. It names both the conditions and the sibling tools, leaving nothing to inference.

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

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

Annotations already declare readOnly/idempotent/closed-world, but the description adds real value beyond them: pagination behavior ('paged at about 8,000 bytes with `cursor`') and the fact that detection is signal-driven. It doesn't disclose limits on what splits, but the pagination detail is useful context the annotations don't cover.

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 well front-loaded: the core action and unit list come first, then range syntax, then modifiers, then routing. Nearly every clause carries information, though the sentence is long and slightly burdensome 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?

For a 9-parameter tool with nested objects and an output schema, the description covers the main flows, id semantics, pagination and sibling contrast, so an agent can invoke it correctly. Detection internals live in the schema, which is appropriate, but a note on default output ordering/shape would make it 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 100%, so the baseline is 3, but the description adds examples beyond the schema: concrete address/range syntaxes (p24#a1b2c3d4..p60#e5f6a7b8, ch-d5a3930d, p142#a7b2a7b2.s3) and the meaning of `chapter`, `language`, `profile` and `overrides`. This meaningfully enriches otherwise-documented params.

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

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

States a specific verb and resource ('split a manuscript into units with stable ids') and enumerates the outputs (chapters, parts, scenes, sentences, dialogue). It also explicitly distinguishes itself from the sibling 'doc.outline lists only styled headings'.

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

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

Gives clear context ('Use it to work chapter by chapter or to get sentence addresses') and points to the alternative doc.outline. It lacks an explicit when-not or a fuller routing list among the many sibling segmentation/inspection tools, so it stops just 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 declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered before the description starts. The description still adds genuine behavioral context: 'one reply, not paged' (a pagination guarantee) and the scoping rule that requesting notes/headers does not change the body counts. It does not discuss cost, limits, or behavior with malformed files, so it is solid but not rich.

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

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

Front-loaded with the counted resource, then the parameter caveat, then the routing sentence, then the operational note – a logical order with no filler sentences. The long enumeration of counted items is dense but each item earns its place because it defines the tool's surface; slightly heavy for a single paragraph.

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 shape need not be described, and the description still pre-announces the returned categories and the non-paged single reply. Combined with annotations covering safety and idempotency, an agent has everything needed to select and call this tool.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes further by explaining the semantics of 'stories' that the schema only implies – that notes and headers are counted separately and 'the body counts stay the body's'. The schema supplies the address-prefix detail for the extra stories, so the description sensibly does not repeat it.

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

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

States a specific verb (count) and resource (body contents of a .docx) and enumerates exactly what is counted: paragraphs, empty paragraphs, words, characters, headings, tables, comments, footnotes, tracked changes by type, styles, top fonts. It is clearly distinguishable from the listed siblings doc.info (file facts/hash) and revision.list (the changes themselves).

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 names two use cases ('size a document or check for leftover revisions') and routes the agent to the right alternatives with the differentiator for each: doc.info for file facts and hash, revision.list for the changes themselves. That is when-to-use plus when-to-use-something-else.

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, so safety is partly covered, but the description adds behavioral context beyond them: it never changes anything, covers nested/split/simple fields and text boxes, and crucially notes a single reply with no pagination. It stops short of describing auth or failure 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?

Front-loaded with the core action, then scope, then usage routing in a compact run of sentences. The enumeration of field codes and stories is dense but earns its place; slightly longer than strictly necessary but no filler sentences.

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?

Though an output schema exists (so return values needn't be documented), the description still names the returned attributes (address, story, code, type, shown result, staleness) and the read-only/no-pagination contract. For a 3-param listing tool with rich annotations, nothing an agent needs is missing.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds meaning on top: stories defaults to all with the enum members spelled out, and type's single-value filtering is explained with a concrete example ('TOC'). This clarifies intent beyond the schema's own description text.

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?

Starts with a specific verb+resource ('List every field') and enumerates exactly which field kinds are covered (PAGE, TOC, REF, SEQ, XE, citations) plus the scope of stories and field shapes. An agent can distinguish this from field_update and other list tools without opening any schema.

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

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

Explicitly states when to use it ('before field.update to see what is stale, or to find citations'), names the sibling it precedes, and clarifies the negative ('it never changes anything'). The condition selecting this tool is 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?

Goes well beyond the annotations: it discloses which fields are rewritten, that citations are never changed, the exact 'skipped' set (INDEX, SECTIONPAGES, SECTION, NOTEREF, unresolvable REFs), the ENGINE_UNAVAILABLE failure mode, that it is backed up and undoable, and that it is slow. Annotations only supply the safety profile.

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?

It is dense but front-loaded, leading with the recompute action and its scope, with zero filler sentences. The single-block layout without sub-structure costs it a point but nothing is wasted.

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

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

For a mutation tool with several optional params and an output schema, everything an agent needs is present: prerequisites, ordering, alternatives, error semantics, performance expectation, and the skipped-field contract. No reliance on return-value explanation is needed since an output schema exists.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by framing set_update_on_open as a cheap alternative to the full recompute and by tying dry_run and error codes to behavior, rather than merely restating field names.

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 precise verb ('Recompute ... results') and an exact resource set (TOC, PAGE, NUMPAGES, SEQ, REF/PAGEREF), and names the write behavior (tracked changes). An agent can tell this apart from field_list, toc_insert, and xref_add without opening a schema.

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

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

Gives explicit ordering ('Run after toc.insert, caption.add or xref.add') and a named alternative path ('set_update_on_open instead sets w:updateFields so Word updates them on opening'), plus the prerequisite (needs soffice). This is when-to-use, when-not, and alternative all in one.

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: it discloses exactly what moves (the store, backups and log), that existing history is never overwritten (BATCH_CONFLICT), and that dry_run moves nothing. These are the mutation semantics an agent needs and are not derivable from readOnlyHint=false/destructiveHint=false alone.

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

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

Front-loads purpose in the first sentence, then layers the mechanism and parameter conditions. It is dense and multi-clause, but each clause carries actionable information about behavior or parameters, so little waste remains.

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 an output schema present, return values need no explanation, and the description still usefully names reply fields (`adoptable`, `candidates`) and the BATCH_CONFLICT conflict state. For a filesystem-mutating tool this is complete enough to invoke 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 coverage is 100% so the baseline is 3, but the description adds real meaning: it explains that `store` is needed when several candidates match and points to the reply's `candidates`, and frames `force`/`dry_run` in operational terms. Minor value-add beyond the already-thorough 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?

States a specific verb+resource ('Re-attach a moved or renamed document to its old undo history') with a clear downstream consequence ('so history.undo and history.restore work again'). This distinguishes it cleanly from history_restore, history_undo, and history_orphans without opening any schema.

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

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

Gives explicit trigger conditions (moved or renamed document), names the discovery alternatives (doc.open's `adoptable`, history.orphans), and specifies when each param is needed ('store when several match', 'force adopts a file edited since', dry_run). An agent knows exactly when to reach for this versus 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 cover the read-only, idempotent, closed-world profile, but the description adds real behavior: newest-first ordering, pagination with default limit 20 and cursor taken from the reply's `next`, and the orphaned-store read path. It slightly over-specifies return fields that the output schema already defines, and repeats 'read-only' from 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?

Dense but front-loaded, leading with the verb, resource, and ordering before filters and alternatives. It wastes a little space repeating 'read-only' (already in annotations) and listing return fields the output schema covers.

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 paged list tool with an output schema, the description covers scope, ordering, filtering, pagination, the alternative read mode, and sibling routing. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters including the `kind` enum and the cursor/limit semantics. The description mostly restates these (enum values, default 20, cursor = reply's `next`), adding only a marginal gloss on `store` reading an orphaned store, 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?

States a specific verb and resource ('List the document's undo log') plus ordering ('newest first') and enumerates what each entry contains. This distinguishes it cleanly from history_search, history_undo, and history_restore, which are named as different 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?

Explicitly says what it is for ('Use it to find the op_id for history.undo or history.restore') and names the contrasting alternative ('history.search finds a quote in the log'). It also explains the `kind` filter and the `store` orphaned-store case, giving the agent clear routing conditions.

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

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

Annotations already declare readOnlyHint, idempotentHint and closed-world, so the safety profile is given. The description still adds real behavioral context beyond them: orphaned history 'is never deleted automatically', and it names the fields each entry carries. It does not add auth or rate-limit caveats, so not a 5.

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

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

Front-loads the core definition, then the scope extension, then the routing sentence, ending with 'Read-only.' No sentence is filler, though the first sentence is heavily packed with clause-nested enumerations that take a second read 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?

An output schema exists, so return values need no prose, and the description uses the space for what the schema cannot carry: orphan classification, the `dir`/`unknown` edge cases, non-deletion behavior, and next-step siblings. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100% and the schema only says 'Also scan this folder'. The description adds meaning the schema lacks: when `dir` is supplied, the scan covers `dir`/.doc-control in addition to the app-data stores. That is genuine semantic enrichment beyond the one-param baseline of 3.

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

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

States a specific verb+resource ('List undo stores whose document is gone') and immediately enumerates what counts as an orphan (moved, renamed, deleted) plus the special `dir`/.doc-control case and the `unknown` bucket. This cleanly separates it from siblings like history_list, history_search and history_purge.

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

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

Explicitly routes the agent: history.adopt to re-attach to a moved document, history.list/history.restore with `store` to read from it, history.purge with `store` to delete it. It also scopes when the optional `dir` matters, so both when-to-use and what-to-use-next are covered.

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

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

Annotations already declare destructiveHint=true, and the description goes well beyond them: it discloses the two-step confirm protocol, the mid-flight change refusal, that a tombstone entry remains, that backups are NOT removed, and that purged entries can no longer be undone or restored. This is exactly the behavioral context a mutation tool needs.

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

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

A single dense paragraph that front-loads the mode selection and then the destructive/confirm mechanics. Every sentence carries information, though the level of detail makes it slightly heavier than needed.

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, six-parameter mutation tool, the description covers scope, safety workflow, side effects, and prerequisites. An output schema exists, so return-value explanation is legitimately omitted. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds genuine meaning: `before` is ISO 8601 in UTC, `store` is an orphaned store (pointing to history.orphans), and `confirm`/`dry_run` are coupled as a token round-trip. It clarifies interaction between params rather than merely restating them.

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

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

States a specific verb+resource (delete undo history) and immediately scopes the two modes (whole log via `all` vs entries before a date via `before`), plus the doc-vs-store targeting. An agent can distinguish it from history_undo, history_restore, and history_list without opening a schema.

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

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

Prescribes the exact workflow: run with dry_run first to see what would go and obtain a confirm token, then repeat with confirm. It also recommends history.list as a pre-check and warns that a log changed between steps is refused. Explicit when/how-to-use with an alternative named.

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 (readOnlyHint=false, destructiveHint=false) already establish this is a non-destructive write, and the description is consistent with that. It goes further by disclosing that changes are backed up, logged and undoable, that dry_run previews, and that a specific BATCH_CONFLICT error arises when a placement was edited. Minor gaps remain (no mention of permission requirements or return behavior, though an output schema exists).

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

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

Front-loaded with the core operation and then the routing/parameter rules; almost no wasted words. It is a dense single paragraph with stacked parentheticals (e.g. "tracked: false: plainly, for a change the writer approved") that take effort to parse, keeping it just short of a 5.

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 10-parameter mutation tool with full schema coverage and an output schema, the description covers the operational flow, the main alternative, and the key error conditions. Slightly ambiguous phrasing around tracked:false leaves a small interpretive gap, but nothing essential for a correct call is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics beyond the schema: the consequence of omitting `change`, the role of `after` as an override of the old place, and the meaning of `tracked: false`. This is meaningfully more than the per-parameter schema text 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?

States a specific verb and resource with scope: bring back paragraphs a logged write deleted or changed, and specifies the default form (tracked insertion). It also names a sibling it is not (history.undo reverts a whole write instead), so an agent can distinguish it without opening other schemas.

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

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

Explicitly says where op_id comes from (history.list or history.search), what happens without `change` (every deleted paragraph returns after the paragraph now holding its old place), what `change` selects, when `after` is required, and the alternative (history.undo). When-to-use and when-to-use-something-else are both covered.

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 read-only, idempotent and closed-world behavior, but the description adds important operational context: the search order, the scope of paragraphs before and after each write, default exact matching, how ignore flags loosen it, what match_level returns, and the limit/total 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?

Front-loads the core purpose and then moves through usage, matching behavior, store support, and limits in a dense but logical order. It is somewhat long and repeats a few schema/annotation facts such as read-only and limit default, but the complexity justifies most of the length.

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 rich schema, annotations and output schema, the description covers the important gaps: scope of the undo log, default match mode, flag interactions, hit offsets, total counts, sibling alternative, and orphaned-store support. An agent has enough context to call it correctly without opening additional tools.

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

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

Schema description coverage is 100%, so the schema already documents all parameters in detail. The description adds value by clarifying that matching is exact by default and that ignore_case/ignore_accents loosen it, plus how match_level folds case, accents and punctuation, but much of this overlaps with the schema text.

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

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

States a specific verb and resource: search the undo log for a quote across logged requests and surrounding paragraphs, newest first. It distinguishes from the sibling text_find by explicitly saying text.find searches the current document instead, and it names the downstream tools that consume its op_id.

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

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

Gives a clear when-to-use case: finding when a passage was changed or deleted, and retrieving op_id for history.undo or history.restore. It also names the alternative text.find for current-document searches, and notes the orphaned `store` case, which is an uncommon but important context.

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

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

Annotations only declare it is not read-only and not destructive; the description adds substantial behavior: the undo is itself logged, BATCH_CONFLICT if a touched paragraph/part was edited since, dry_run previews without writing, and expect.sha256 guards against a changed file. This is context beyond the annotation set, with no contradiction of destructiveHint=false (it restores prior state rather than destroying it).

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

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

Front-loaded with the core action and family of covered writes, then constraints, then alternatives. Dense parenthetical enumeration is efficient though the long run-on sentence carries a lot; nearly every clause 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?

With an output schema present, return values need not be explained, and the description fully covers scope, default behavior, conflict handling, write-guard, preview mode, and sibling alternatives. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real semantics: op_id comes from history.list and defaults to the latest write still in effect, dry_run means check-without-write, and expect.sha256 refuses a changed file. It complements rather than merely restates 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?

States a specific verb (take back/undo) and resource (a logged write), enumerating the operation classes it covers and the scope of restoration (paragraphs and parts to their pre-write state). It is immediately distinguishable from history.restore and revision.reject, which are named as different 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?

Gives explicit selection logic: undo the latest write in effect by default, or specify an op_id from history.list. It names alternatives and their conditions (history.restore for bringing back single deleted paragraphs, revision.reject for tracked changes by author/id) and explains the BATCH_CONFLICT refusal path.

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 the safety profile (readOnlyHint=false, destructiveHint=false) and the description adds real behavioral context beyond them: the insert is tracked as revisions, it is backed up and revertible via history.undo, dry_run previews without writing, and expect.sha256 rejects a file changed on disk. It stops short of describing pagination/output shape, though that is largely covered elsewhere.

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

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

Dense but front-loaded: the core action and placement come first, then prerequisites, then safety/undo guarantees. Every clause carries information, though the single run-on sentence packs several concerns together and could be segmented for faster scanning.

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 mutation tool with 7 parameters, an output schema, and nested objects, the description covers prerequisites, tracked-revision semantics, undo, write guarding, and the returned address. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds value by clarifying that `after` is a body-paragraph address (with the p40#a1b2c3d4 format), that `title` defaults to "Index" and "" suppresses it, and what expect.sha256 does on mismatch. That is genuine meaning beyond the field names.

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

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

States a specific verb and resource ("Insert an index (an INDEX field)") plus the exact placement scope ("after a body paragraph `after`"), and the tracked-insertion nature. It also implicitly distinguishes itself from index_mark, which only marks entries, so an agent can route between the two without opening either schema.

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

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

Gives explicit sequencing guidance ("Mark entries first with index.mark") and names the alternative that will NOT work ("field.update leaves indexes alone"), redirecting the agent to Word/F9 instead. It further states when to use dry_run and expect.sha256, so both the normal and guarded invocation paths are 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?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false) by disclosing that the write is a tracked insertion, that it is backed up and reversible via history.undo, that dry_run previews without writing, and that a stale sha256 yields DOC_CHANGED_ON_DISK. It also states what the call returns, which is real behavioral context 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?

Front-loaded with the core action and scoping, and the workflow sentence follows naturally. It is information-dense with back-to-back clauses, but each sentence carries distinct, non-redundant content rather than 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?

For a 7-parameter mutation tool with nested objects and an output schema, the description covers ordering against the sibling index_insert, the entry-format grammar, safety (backup/undo/dry_run/sha256 guard), and the return payload. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3; the description adds value by expanding the entry syntax to the three-level 'Term:Sub:Detail' form and by showing the range address shape (p8#a1b2c3d4:10-15) that `at` requires. It does not explain tag/author or the expect object's semantics beyond the guard 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?

States a specific verb and resource ('Mark an index entry: insert an XE field') and pins down the exact insertion point ('right after a range') with a concrete address example. It is clearly distinguishable from the sibling index_insert, which only finalizes the index once marks exist.

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 workflow guidance: 'Mark every occurrence you want listed, then insert the index once with index.insert' tells the agent both the per-occurrence usage and the correct sequencing against the alternative. It also names dry_run as the preview path and expect.sha256 as the write guard condition.

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 annotations already flagging a non-read-only write, the description discloses substantial behavior beyond them: which edits are tracked vs. require untracked: true, header-sharing/rewrite rules, inheritance refusal, and the all-or-nothing UNSUPPORTED_CONTENT failure mode. This is unusually rich disclosure 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?

Purpose is front-loaded and nearly every clause carries needed operational detail (tracking rules, error semantics, flag conditions). The long run-on sentences with dense parentheticals reduce readability, but little is genuinely redundant.

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

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

For a 7-parameter mutation tool with nested objects and an output schema, the description covers the workflow, tracking model, guards, and failure behavior. Return values are delegated to the output schema, and nothing an agent needs to invoke it correctly appears missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds interpretation: '{PAGE}, {NUMPAGES}, {chapter} become fields; null inherits' and 'dry_run lists the changes' go beyond the schema's terse 'Preview only; write nothing.' It largely mirrors the plan schema's inheritance rules, keeping it at 4 rather than 5.

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 opening clause ('Bring the document to a page plan, the shape layout.get returns') states a specific action and resource and explicitly anchors the tool to its read sibling, so an agent can distinguish it from layout_get. It is slightly indirect in phrasing rather than a crisp verb+resource, but the target (per-section start, break, numbering, header/footer text) is concrete.

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 supplies a clear workflow: 'Edit the layout.get result and send it back,' and gives conditions for the optional flags (untracked: true for new header parts, dropped references, two_sided, mirror_margins; dry_run lists changes). It names the source tool rather than a competing sibling, so alternatives are contextualized but no explicit when-not guidance is given.

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

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

Annotations already declare readOnlyHint/idempotentHint/openWorldHint, so the safety profile is covered; the trailing 'Read-only' largely restates it. The description adds genuine behavioral context beyond the annotations: 'null means inherited from the previous section' and the coupling to layout.apply.

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

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

Front-loads the core action ('Read the page plan') and packs the field inventory into one dense sentence. It is information-dense rather than padded, though some return-field detail borders on duplicating the output schema.

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 dedicated output schema present, the description needn't explain return structure, yet it still gives enough about scope, inheritance semantics, and sibling relationships for correct invocation. Nothing critical for calling the tool is missing.

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

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

Schema description coverage is 100% and the single 'doc' parameter is fully documented ('Path to the .docx.'). The description adds no parameter-level detail (formats, constraints) beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource ('Read the page plan') and enumerates exactly what it returns: per-section start address, break, page numbering, first-page difference, and header/footer text. It also names the sibling it differs from (section.list gives part names instead of text), so an agent can distinguish it without opening schemas.

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

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

Explicitly routes the agent: 'Edit it and pass it to layout.apply to change the layout' describes the round-trip workflow, and 'section.list gives the same setup with header/footer part names instead of text' gives the alternative. It stops short of an explicit when/when-not conditional, but the tool relationships are 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 destructiveHint=true but give no detail; the description adds the specific failure mode (UNSAVED_CHANGES), the two ways to proceed (save vs discard), and a safety guarantee ('nothing unsaved is ever lost silently'). This is meaningful behavioral context well beyond the annotations.

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

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

Three tight sentences, front-loaded with the core action and each subsequent sentence adding decision-relevant information (refusal condition, alternative tool, return value). 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?

With an output schema present, return values need no explanation, and the description still notes 'Returns whether it saved.' Combined with the error-code disclosure, safety guarantee, and sibling routing, nothing needed to invoke this 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?

Schema description coverage is 100%, so the baseline is 3. The description's gloss on save ('save, then close') and discard ('drop them') largely restates the schema; the added value is the interaction rule with the UNSAVED_CHANGES refusal, which is more usage guidance than parameter 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?

States a specific verb and resource ('Close the document in its Word or LibreOffice window') and ties it to the live_open attachment context, which cleanly separates it from sibling live_save. An agent can distinguish it from the other live_* tools without opening any schema.

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

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

Explicitly states the when: refused with UNSAVED_CHANGES if there are unsaved changes, unless save or discard is passed. It also names the alternative ('Use live.save to keep the window open'), giving a clear routing decision between close and save.

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 readOnlyHint, idempotentHint and openWorldHint=false, so 'Read-only' is somewhat redundant. The description adds real value beyond the annotations, however: it discloses the prerequisite (document must be attached via live.open, else ENGINE_UNAVAILABLE) and the address format returned. That prerequisite/error disclosure is the kind of context annotations cannot 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?

Front-loaded with the core action, then usage trigger, alternative, and prerequisite. Slightly dense with parentheticals, and 'Read-only' duplicates the annotations, but every sentence still 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 values need no elaboration, and the description still covers the prerequisite, the trigger, the alternative, and the downstream consumers. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, giving a baseline of 3. The description references the live.open attachment requirement but adds no syntax or meaning for 'doc' or 'engine' beyond what the schema states.

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

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

States a specific verb ('Read') and resource ('what the user has selected in Word or LibreOffice right now'), plus the paragraph address returned. It explicitly distinguishes itself from live.select, so an agent can tell the two apart without opening either schema.

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

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

Gives an explicit trigger ('Use it when the user points at text'), names the alternative ('live.select moves the selection instead'), and points to downstream tools (doc.batch, text.replace). When-to-use and what-not-to-do are both covered.

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?

Adds real behavioral context beyond annotations: the error states ENGINE_UNAVAILABLE and DOC_AMBIGUOUS, the app-default resolution, and the assurance it 'never changes the document'. Annotations (readOnlyHint=false, destructiveHint=false) already sketch the safety profile, and the description is consistent with them.

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

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

Front-loads the core action before the conditional and error clauses, and each sentence carries information. It is dense and slightly clause-heavy, but nothing is plainly redundant.

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 prerequisite/attach tool with an output schema already covering return values, it supplies prerequisites, error conditions, and sibling ordering. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds defaulting semantics the schema does not: 'app ... default the one reachable, see live.status' and 'front: false keeps it behind'. It enriches the two non-obvious parameters beyond their 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?

States a specific verb cluster (attach/find/open/focus) on a specific resource (the Word or LibreOffice window holding a document). It clearly distinguishes itself from the plain doc_open sibling by tying the operation to 'live editing' and window attachment.

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 instructs to 'Call it before live.select, live.get_selection, live.save, live.close and doc.batch with engine live', naming both the prerequisites and the dependent siblings. The 'front: false keeps it behind' note and the 'see live.status' pointer give concrete alternative-selection context.

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

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

Annotations already cover read-only/idempotent/closed-world, so the description adds the valuable side-effect context: in a rendering client a click performs an in-editor jump with 'no assistant turn', while other clients just receive the list. This is genuine behavioral disclosure beyond the structured 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?

Front-loads the core purpose in the first clause, then layers client behavior, data shape, and the sibling alternative. Single dense paragraph with no filler, though the nested clauses make it mildly harder to scan than a bulleted form.

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 an output schema present and full annotation/schema coverage, the description only needs to add call-time semantics, which it does via the mode behavior and the client-dependent click effect. Nothing critical an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100% and every parameter is documented in the schema itself, including mode, engine, at/find_phrase, and the at-vs-find_phrase fallback. The description only restates that each place has a label plus an at or find_phrase, adding little beyond the heavy schema lifting, so baseline 3 applies.

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

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

States a specific verb and resource ('Show the user a list of places as clickable buttons') and differentiates from the sibling live_select by noting it jumps to one place directly versus this tool's list-at-once behavior. An agent can distinguish it from para_locate/para_list without opening any schema.

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

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

Explicitly frames the use case ('walk a writer through findings') and names the alternative ('live.select jumps to one place directly'), plus notes behavior for non-MCP-App clients. It doesn't spell out when NOT to use it, but the routing to live_select 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 only declare readOnlyHint=false, destructiveHint=false, openWorldHint=false. The description adds non-obvious behavior: it overwrites the on-disk file with the app's version and takes no backup, plus the prerequisite that the doc must already be attached with live.open. That is meaningful disclosure beyond the structured fields, and it does not contradict destructiveHint=false since a normal save is not a destructive 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?

Three tight sentences: action first, then the sequencing/alternative, then the risk disclosure. Every sentence carries distinct load with no redundancy or 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?

Output schema exists, so return values need not be explained. The description covers the prerequisite (live attachment), the persistence workflow, the close-and-save alternative, and the overwrite/no-backup consequence - everything needed to invoke 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?

Schema description coverage is 100% and both parameters are documented in the schema (doc path or live-app file name; engine enum with default). The description adds no per-parameter syntax or format detail beyond noting the live.open attachment context, so the baseline 3 applies.

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

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

States a specific verb (save) and resource (the document open in Word/LibreOffice, attached via live.open) and scopes it to acting inside the app. An agent can immediately distinguish this from live_open, live_close, and doc_batch without opening any 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?

Explicit sequencing guidance: call after live edits via doc.batch with engine live to persist them, and the alternative live.close with save: true is named for the save-and-close case. This is exactly the when-to-use-vs-alternative routing an agent needs.

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

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

Annotations only say readOnly=false / destructive=false; the description goes further by disclosing the exact side-effect scope ('Changes only the selection'), the live.open dependency, and the failure modes (STALE_ADDRESS, ANCHOR_NOT_FOUND, ANCHOR_AMBIGUOUS). That is material behavior an agent cannot infer from the structured fields.

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

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

Front-loads the core action and keeps everything in one dense but purposeful block with no filler sentences. It is slightly run-on with stacked parentheticals, which costs a point on 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 an output schema present, return values need no explanation, and the description covers purpose, prerequisites, alternatives and error codes for a 9-parameter tool. Nothing an agent needs in order to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents every parameter, including the match_level nuances. The description restates the at/find_phrase/paragraphs_after mechanics without adding syntax or format beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Show the user a place in Word or LibreOffice: select a paragraph, or ... put the cursor at its start') and gives concrete addressing forms (at `p142#a7b2a7b2`, find_phrase). It distinguishes itself from the live.* family by pointing to live.places for the button variant.

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

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

Gives an explicit use case ('Use it to point at a passage you are discussing'), names a related sibling (live.places offers several as buttons) and a prerequisite (needs live.open). It stops short of stating when NOT to use it, so it is clear context rather than a full routing rule.

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, idempotentHint and closed-world scope, so the safety profile is covered. The description nonetheless adds behavior beyond the structured fields: it will not fail when an app is missing, and it distinguishes a server-driven app from one inferred only from a lock file, which materially affects how the caller should interpret the result.

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

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

Purpose is front-loaded in the first sentence and the usage rule follows immediately; nothing is padding. The first sentence is somewhat clause-heavy and could be split for faster scanning, which keeps this short of 5.

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 documentation is not required, yet the description still describes the key result fields (owner app, drive mode, path, dirty state). Combined with annotations covering read-only/idempotency and the explicit decision guidance, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds meaning the schema does not carry: supplying `doc` widens the report to that document's owning app, its path and its unsaved-changes state. The `engine` enum is not explained beyond the schema, which caps this slightly below 5.

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

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

The description names a specific verb (check) and resource set (Word/LibreOffice, open documents, lock state, unsaved changes) rather than restating the tool name. The `doc` variant is spelled out in detail: which app holds the document, whether it is server-driven or only lock-file claimed, full path, and dirty state. An agent can distinguish this diagnostic tool from live_open/live_close without opening any 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 explicit call sites: 'Call it before live.open' and 'to decide between live editing and the file engine', plus the concrete decision rule that a file open in Word should be edited live or closed first. This is when-to-use guidance with named alternatives and a tie-breaking condition.

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: states mark/note are tracked insertions (rejecting removes the note), the notes part is created when missing, changes are backed up and undoable via history.undo, dry_run previews, and expect.sha256 refuses a changed file. This is exactly the mutation context annotations cannot 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?

Densely packed but front-loaded and every clause carries information; the trailing 'returns id/number/address' is slightly redundant against the output schema, keeping it from a 5.

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 an output schema present and annotations covering the safety profile, the description still supplies the addressing syntax, guard semantics, and undo behavior needed to call it correctly. Nothing an agent needs is missing.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real syntax guidance: the `at` format (p3#a1b2c3d4:10-10 after offset 10, after a range, or paragraph end) and that `text` is the note's one line. Useful elaboration beyond the schema text.

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

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

Opens with a specific verb+resource ('Add a footnote or endnote') and immediately scopes the two supported kinds, distinguishing it from adjacent tools like comment_add. An agent can tell exactly what the tool produces.

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?

Clear context for use (creating a note whose mark attaches at a body point, range, or paragraph end), but it never names alternatives (e.g. comment_add) or states when-not to use this tool. Slightly short of 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 cover safety (readOnly, idempotent, non-open-world), and the description adds real behavioral context beyond them: results are always flagged `estimated`, the two estimation fallbacks, and the ~8,000-byte pagination with `cursor`. It does not discuss accuracy limits of the words-per-page model, so not a 5.

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

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

Front-loaded with the core action and mechanism, and every clause carries information (fallback model, flag, addressing, pagination). It is densely packed into a few sentences and slightly compressed, but no sentence is wasted.

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

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

With an output schema present, return values need not be explained, and the description covers mechanism, the `estimated` caveat, addressing, sibling routing, and pagination. Only minor gaps remain, such as the practical accuracy of the words-per-page estimate when no page marks exist.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds meaning beyond the schema: `at` accepts the address form p142#a7b2a7b2, `by: "page"` yields pages with their first and last paragraph, and `cursor` is tied to the ~8,000-byte page cap. It complements rather than repeats 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?

States a precise verb+resource (estimate the page each paragraph starts/ends on) and explains the estimation basis (rendered page marks, explicit breaks, else a words-per-page model). It distinguishes itself from the closest sibling, para.locate, by naming what that tool adds.

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

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

Gives explicit usage context ("Use it to tell a user roughly where text is") and names an alternative with its differentiating capability (para.locate adds chapter, scene and a find phrase). It stops short of stating when NOT to use it, so it is strong but not exhaustive.

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?

Adds substantial behavioral context beyond annotations: file engine backup, history.undo logging, dry_run preview, expect.sha256 guard, STALE_ADDRESS error, tracked vs plain deletion semantics, engine-live specifics, and refusal conditions. Annotations already declare write/safety profile, and the description enriches it 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?

Front-loads the purpose, then packs operational details into a compact paragraph. Every sentence carries useful information about behavior, alternatives, or error handling, 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?

Complete for a write tool with a rich schema and output schema. It explains mutation semantics, reversibility, guards, errors, and alternatives, and notes the return value (address_map of shifted paragraphs) even though an output schema exists.

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

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

Schema description coverage is 100%, so the schema already documents every parameter thoroughly, including at, doc, tag, author, expect, dry_run, and tracked. The description repeats most of that information (address format, tracked false behavior, expect guard) and adds only minor examples, 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?

States a specific verb (Delete) and resource (paragraph or run of paragraphs), with concrete address examples that distinguish it from siblings like text.replace and doc.batch. The scope and tracked-deletion nature are immediately clear.

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 names alternatives and selection conditions: use text.replace to delete part of a paragraph, doc.batch for several edits all or nothing. Also explains when to use tracked:false versus the default tracked deletion.

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/idempotentHint, so safety is covered; the description goes further by disclosing paging behavior (limit characters, cursor from the reply's next) and the STALE_ADDRESS error condition when the address has changed. "Read-only" repeats the annotation, but the paging and staleness semantics are genuine additions.

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

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

Front-loaded with the core action, then return contents, alternatives, and behavioral caveats in a logical order. The heavy parentheticals make it dense, but each clause carries distinct information rather than 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?

Covers the address format, what is returned, paging, error semantics, and sibling routing. An output schema exists so return values need not be enumerated, yet the description's brief summary of returned fields (text, style, formatting spans, layout facts) is helpful and complete.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds value beyond the schema by illustrating the address syntax (including note addresses like fn3/p1#…) and explaining that limit/cursor drive paging. It also clarifies heading_level semantics (null for body, 1-9 for heading), which the schema does not.

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

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

States a specific verb and resource ("Read one paragraph in full by address") with the exact address formats shown. It distinguishes itself from siblings by naming para.list (many paragraphs) and style.get (a style). An agent can select this tool 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?

Explicitly says when to use it ("before editing a paragraph or to check its formatting") and routes to alternatives for other cases ("para.list reads many paragraphs, style.get a style"). Nothing is left to inference.

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

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

Annotations only cover the safety triad; the description goes far beyond it by disclosing backup-before-write, history.undo logging, dry_run preview, the expect.sha256 guard failing as DOC_CHANGED_ON_DISK, tracked:false semantics with UNSUPPORTED_CONTENT refusals, and live-engine tracking toggling. This is exactly the behavioral context an agent needs 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?

Front-loaded with the action and placement, then mode/guard details. Dense and semi-colon heavy but nearly every sentence carries distinct information; a few clauses (e.g. the tracked:false rationale) shade into what the schema's tracked description already says.

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 10-parameter tool with nested expect object and an existing output schema, the description covers engines, backup/undo, guards, tracked vs plain writes, and even names the return value kind, so the agent has enough to call it correctly without further reading.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds specifics the schema lacks: the concrete paragraph-address example (p3#a1b2c3d4), the either/or relationship of after/before, and the practical meaning of tracked:false and engine live. It goes modestly beyond the structured fields.

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

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

States a specific verb and resource ('Insert one new paragraph with `text`') plus the placement model (after/before an existing one), which cleanly separates it from para_delete, para_get, para_list and text_replace. An agent can identify the tool without opening the schema.

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

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

Gives real routing guidance: 'Use doc.batch for several edits all or nothing', 'style it with style.apply in doc.batch', 'engine live ... after live.open'. It does not explicitly contrast with the nearest sibling (text_replace) but the mode-selection guidance is strong.

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/idempotentHint/openWorldHint=false, and the description reinforces 'Read-only' while adding genuinely new operational context: paging at ~8,000 bytes per reply, limit up to 1,000, and resumption via `cursor` set to the reply's `next`. It also clarifies the null semantics of heading_level. It stops short of stating prerequisites (e.g. whether doc_open is required first) or error 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?

Front-loaded with the resource and the returned fields before the routing guidance and paging caveat, and every clause carries information. The middle sentence is dense and semicolon-packed, which slightly hurts scanability, but nothing is wasted.

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

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

With an output schema present, field-level return documentation is not required, and the description still covers scope, flags, pagination and alternatives for a 6-parameter tool with one required arg. The only real omission is whether the document must be opened via doc_open before calling.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it explains what the flags yield (normalized adds normalised text, pages adds the estimated page, stories adds notes or headers), which tells the agent the output shape each flag unlocks rather than just its boolean type.

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?

Specific verb+resource ('List every paragraph in document order') plus an enumeration of exactly what each item carries (address, text, style, heading level, layout facts). It also names and distinguishes the nearest siblings (para.get, doc.outline, text.find), so an agent can identify it 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?

Explicitly states the use case ('index or scan a whole document') and names three alternatives with the condition that selects each: para.get for one paragraph with formatting, doc.outline for headings only, text.find for searching. This is exactly the when/when-not/alternative structure.

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