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

readOnlyHint=true already signals no document mutation, lowering the bar. The description adds useful lifetime context ('find the passage again after edits') but does not disclose whether the anchor is persisted to the .docx or returned as a session handle, nor what the resulting anchor looks like.

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

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

A single sentence with no filler, front-loading the verb and resource before the rationale. Nothing is 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?

With no output schema, the description carries the burden of explaining the return value, yet it never says what an anchor is handed back as (ID, quote, opaque token) or how to feed it to anchor_resolve. Otherwise adequate for a 3-parameter 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 touches the 'context' parameter implicitly via 'quote with context', but adds no syntax or format detail beyond the schema's own descriptions of 'at' and 'context'.

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 ('Make an anchor... for a range') and clarifies what the product is with a parenthetical ('quote with context') plus its purpose. An agent can distinguish it from a generic create, though it does not name the anchor_resolve sibling it pairs with.

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 clause 'to find the passage again after edits' implies the workflow (create before edits, resolve after), giving implied usage. It does not state when to prefer this over find/locate, nor any prerequisites or exclusions.

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

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

With readOnlyHint=true already covering the safety profile, the description adds real value by disclosing return shape (range, score, match kind, ambiguous candidates) — important since there is no output schema — and the behavioral guarantee that exact mode never yields fuzz/fold results.

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

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

Three sentences, front-loaded with the core action and return content before the mode caveat. The match_level sentence is dense and reads somewhat tangled, 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 read-only resolver with a nested anchor object and no output schema, the description supplies the missing return-value context and the exact-vs-folded matching behavior. It is nearly complete, with only the relationship to alternative lookup tools left implicit.

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 mode, match_level and the anchor fields are already fully documented in the schema. The description restates the mode/match_level semantics rather than adding new syntax or edge-case meaning, so it sits 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?

Clear verb+resource: "Find an anchor's passage" with the specific outputs (range, score, match kind, or ambiguous candidates). It contrasts well with anchor_create semantically, though it never names or distinguishes itself from adjacent lookup siblings like find or locate.

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 a conditional rule ("mode exact never returns a fuzzy match") and explains the match_level ladder, which implicitly tells the agent when results will be strict vs folded. But there is no explicit when-to-use-this-vs-alternatives guidance against find/locate/anchor_create.

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?

readOnlyHint=false is consistent with a mutation tool, and the description usefully discloses atomicity ('all or nothing'), BATCH_CONFLICT semantics, dry_run, and tracked mode. However it omits permissions/auth needs, the live vs file engine implications, and any response/rollback behavior, which matters for a mutation tool. Adds real value but leaves gaps.

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 a single very dense run-on sentence cramming all batching rules together. Front-loading is partial and there is no structure separating the atomicity rule, valid op groups, and dry_run, making it harder to parse than its length warrants.

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 tool with nested objects, no output schema, and atomic mutation semantics, the description covers the key behavioral rules but omits return/response behavior, failure handling beyond BATCH_CONFLICT, and the meaning of the 'tracked' constraint ('the only mode, true'). Adequate but with clear gaps.

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

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

Schema description coverage is 88%, so the schema already documents the nested op kinds and their parameters in detail. The description echoes the op groups and adds 'by ids, author, address range or all' for revision resolution, but mostly repeats what the schema provides. Baseline 3 is appropriate.

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

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

The description names the exact operation groups that can be combined (text.replace, para.insert, comment.add, revision.accept, etc.) and states the core behavior: apply them together, all or nothing, with dry_run previewing. It is clear this is an atomic multi-operation batch tool, though the run-on enumeration makes the central 'batch multiple ops atomically' purpose harder to extract than it should be.

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 implies when to use it (grouping related ops that must apply as one unit, or resolving revisions) and mentions dry_run for previews, but it never states when NOT to use it or routes the agent to the many single-purpose siblings (style_update, table_row_delete, etc.). The grouping constraints read ambiguously as either examples or a whitelist of valid combinations.

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 this as a read-only operation, so the safety profile is covered. The description adds value by enumerating the return payload (version, engines, frozen build state, operations), which is useful given there is no output schema, but it does not disclose any additional behavioral traits like auth requirements or rate limits.

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

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

The description is a single, front-loaded sentence with no wasted words. Its comma-separated list is compact, though the lack of a verb makes it slightly less structured than an ideal statement of purpose.

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

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

With no output schema, the description must convey return values, and it does so by listing the four key pieces of information. It is complete enough for an agent to understand what to expect, though it does not specify the format or depth of the operations list.

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

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

The tool takes no parameters, so the baseline is 4. The description does not need to explain parameter semantics, and it correctly focuses on the output content instead.

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

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

The description clearly states the information the tool provides: API version, engines, build status, and list of operations. It is specific about the resource and contents, but it does not differentiate this tool from potential siblings like 'info' or 'help', which likely return overlapping metadata.

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 offers no guidance on when to use this tool versus alternatives. It simply lists what is returned, with no context about appropriate scenarios or exclusions.

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

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

Annotations provide only readOnlyHint=false, so the description carries real weight and delivers: the insertion is tracked ('as tracked insertions'), the internal structure (SEQ field, hidden bookmark for cross-references), the dependency on fields.update to refresh the number, and the return value ('address of the caption'). This is substantial behavioral context beyond the single annotation.

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

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

Front-loaded with the action and reasonably dense; each clause (tracked insertions, structure, refresh dependency, return value) carries information. The single long sentence is a bit packed with structural detail, but nothing is clearly wasteful.

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

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

With no output schema, the description correctly states the return value ('address of the caption') and covers the key mutation behavior and cross-reference workflow. It does not touch the optional params (dry_run, expect, author, tag), but the schema documents those, so the description is nearly complete for a complex 9-param tool.

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

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

Schema description coverage is high at 89%, so the schema already documents each parameter. The description restates the label options, text, and above/below placement, mapping to schema fields but adding no format or constraint detail beyond what the schema provides. 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?

Starts with a specific verb and resource ('Add a caption paragraph'), names the placement scope (above or below a body paragraph), and details the exact artifact produced (label, SEQ field, text, hidden bookmark). An agent can distinguish it from nearby siblings like xref_add and toc_insert 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?

The mention that 'the number is refreshed by fields.update' implies a follow-up workflow, which is useful. However, there is no explicit statement of when to choose this tool over alternatives (e.g. xref_add for referencing, toc_insert), so usage is only implied.

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?

readOnlyHint=true already establishes the safe-read profile, so the description's remaining burden is lighter. It adds genuine value by disclosing output ordering (each root followed by its replies) and that resolved state and location are included, but says nothing about pagination behavior or the ~8,000-byte cap noted only in the schema.

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 sentence with the ordering semantics front-loaded and zero filler. Every clause (thread order, resolved state, location) 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?

For a read-only list tool with no output schema, the description covers the essentials: what is returned, in what order, and with what attributes. It stops short of describing pagination continuation, though the cursor parameter in the schema partly compensates.

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 all five parameters (doc, limit, author, cursor, resolved) are already documented in the schema. The description adds no parameter-level detail beyond what the schema provides, making the baseline 3 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 comments) and adds meaningful scope detail: thread order, resolved state, and location. It is clearly a comments reader, but it does not explicitly distinguish itself from siblings like revisions_list or history_list beyond the 'comments' noun.

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

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

No when-to-use or when-not-to-use guidance and no alternatives named. The presence of filter parameters implies a filtered listing, but the description never tells the agent when this tool is the right choice over related list tools.

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

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

Annotations only supply readOnlyHint=true; the description adds genuinely useful behavior beyond that: the output is a newly authored .docx, differences are rendered as tracked changes, and the source documents are never touched. It does not mention author/date defaults or collision behavior on the output path, but the core side-effect profile is disclosed.

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

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

A single, front-loaded sentence with three dense clauses and no filler; the artifact being created comes first, followed by the tracked-change semantics and the safety guarantee. 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?

For a six-parameter file-producing tool with full schema coverage and no output schema, the description supplies the crucial facts: it creates a new file, differences become tracked changes, and inputs are untouched. Only the author/tag/date defaults and failure modes (e.g., output already exists) are left to the schema.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters (old, new, output, author, tag, date) including constraints like 'must not exist'. The description adds only the notion of two versions and non-modification of inputs, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb and artifact: 'Write a new redline .docx from two versions', plus the defining behavior (every difference as a tracked change). An agent can tell exactly what it produces. It stops short of distinguishing itself from a close sibling such as 'diff', leaving the comparison target implicit.

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

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

No explicit when-to-use guidance, no prerequisites, and no named alternative. The sentence 'the inputs are never modified' implies the safe comparison context but does not state when to pick this over siblings like 'diff', 'restore', or 'revisions_list'. Usage must be inferred entirely from the name.

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?

readOnlyHint=true already tells the agent this is a safe read, so the annotation carries the safety profile. The description adds one genuinely useful behavioral fact — that the result includes a cross-version address map — but says nothing about pagination behavior or result size, even though limit/cursor exist.

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 tight sentence with no filler, and the core operation is front-loaded. The phrase 'cross-version address map' is jargon-heavy and unexplained, which slightly reduces immediate comprehension.

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 diff tool with no output schema, the description conveys the shape of the result (alignment plus address map) but omits return format details, pagination semantics, and any differentiator from `compare`. Adequate but with clear gaps given the tool's complexity.

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

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

Schema description coverage is 100% with five well-documented parameters, so the schema does the heavy lifting and the baseline is 3. The description adds no additional meaning about `old`/`new` ordering, `collapse_runs`, or cursor usage beyond what the schema already 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?

The description names a specific operation (paragraph alignment between two document versions) and an output artifact (a cross-version address map), so the resource and result are clear. It does not, however, distinguish itself from the sibling `compare`, which an agent would plausibly confuse with it.

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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives despite a closely related sibling tool (`compare`) existing in the same namespace. The agent is left to infer the selection criteria entirely.

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?

readOnlyHint=true already covers the safety profile, and the description adds real context: it discloses scope guarantees (complex fields, nested fields, fields split across runs, simple fields, text boxes) and a computed output ('whether the result is stale'). It doesn't cover performance, ordering, or error behavior, but for a read-only list this is meaningful added detail.

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

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

Two tight sentences with the resource front-loaded and no filler. The parenthetical enumerations are dense but each earns its place by clarifying coverage.

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

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

With no output schema, the description carries the return-value burden and does so by naming the returned attributes including the computed staleness flag. Combined with a fully-covered parameter schema and read-only annotation, it is nearly complete; only usage routing 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 all three parameters are already documented. The description reinforces 'by story' and gives field-type examples (TOC, ADDIN ZOTERO_ITEM, CITATION) that align with the type filter, but adds no syntax or defaults 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+resource ('list every field of the document') and enumerates what is returned (address, instruction code, type, result text, staleness). It distinguishes itself from the sibling fields_update by describing a read/dump, though it never names an alternative explicitly.

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?

There is no when-to-use statement, no prerequisites, and no mention of the obvious alternative fields_update. The usage is only implied by the word 'list', so an agent must infer the context itself.

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

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

Beyond the lone readOnlyHint=false annotation, it discloses the write mechanism (old result struck, new inserted as tracked changes), the failure mode and error code (ENGINE_UNAVAILABLE naming stale fields), the skip semantics for SECTIONPAGES/SECTION/NOTEREF/INDEX/error REFs, and that citation fields are never touched. This is rich behavior that no structured field conveys.

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

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

The purpose is front-loaded and every sentence carries distinct behavioral content with no repetition. It is dense, however, with long semicolon-and-parenthesis chains (especially the INDEX and REF explanations) that make it harder to scan than necessary.

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 no output schema and no annotations beyond readOnlyHint=false, this covers the essentials: preconditions, fallback, side effects, and which results are omitted. What is returned is only hinted at via 'listed under skipped' rather than described, leaving a small gap.

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

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

Schema coverage is high at 83%, so the baseline is 3, but the description meaningfully augments set_update_on_open by explaining the w:updateFields effect and that no LibreOffice run occurs. tag, author, expect, and dry_run receive no added meaning 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?

The opening states a precise verb and resource: recompute the body's TOC, page, page-count, sequence and reference field results and write only those result runs as tracked changes. It is immediately distinguishable from siblings like fields_list, index_mark, or toc_insert.

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 conditions are given: it refuses with ENGINE_UNAVAILABLE without LibreOffice, and set_update_on_open is offered as the alternative that defers updating to Word. It also enumerates exactly which field types are not recomputed. It does not, however, route to any sibling tool (e.g. fields_list, index_insert) for related workflows.

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

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

Beyond the single readOnlyHint annotation, the description discloses real behavior: results are capped, paging is via cursor, the first page carries `total` or a truncated `total_at_least`/`more: true` when the time budget aborts counting, and `match_level` folding changes which matches survive. That is substantive operational context an agent could not get from the annotations 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?

The core purpose and output shape are correctly front-loaded, but the second sentence runs long and dense with parenthetical edge cases about `query_word` nullability, soft hyphens and 255-character cutoffs. Several clauses concern fields that are not even input parameters, so the paragraph is heavier than it needs to be.

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

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

With 11 parameters and no output schema, the description usefully carries the return-value story (cursor, total variants, match_level tags) that the schema cannot. It leaves usage routing and the `stories`/`context` semantics to the schema, which is acceptable given their full coverage, but the lack of any sibling differentiation is a residual gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine cross-parameter meaning the schema does not: `match_level` cannot combine with `regex` (unless `exact`) or with `ignore_case`/`ignore_accents` left false at a folded level, and it disambiguates the two senses of 'exact'. It also explains the folded-level tagging semantics of a match's own `match_level`.

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

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

The opening states a specific verb and resource — find text or a regex in a document — and immediately characterizes the result shape (paragraph ranges, capped, cursor-paged). It is clear what the tool does, though it never contrasts itself with near-neighbors like `locate` or `history_search`, so an agent must infer the boundary.

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

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

There is no explicit when-to-use or when-not guidance; the description never names an alternative tool or states the condition that selects this one over `locate`. The paging hint ('more are reached with cursor') implies the retrieval workflow but is not framed as usage direction.

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?

readOnlyHint=true already tells the agent this is a safe, non-mutating lookup, so the description only needs to add context. It does add that the response includes a `batch_operations` section listing kinds like text.replace and comment.add, which is genuinely useful output-shape information. It stops short of describing structure depth or whether it is static documentation.

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 sentence that front-loads the primary purpose (JSON Schema) before the secondary note about batch operation kinds. The parenthetical example and trailing clause make it slightly run-on, 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 no output schema, the description carries the burden of explaining returns, and it does name the two things you get back: an operation's schema and the batch_operations listing. An agent could call this correctly, though the exact response envelope for the no-`op` case is left implicit.

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 a single parameter at 100% schema description coverage, so the schema already documents `op` as 'Operation or batch operation kind.' The description restates the same dual meaning (operation vs batch operation kind) without adding format, enumeration, or example values for `op` 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?

The description states a concrete verb+resource: it returns the JSON Schema of one operation or of all operations, and additionally exposes batch operation kinds under `batch_operations`. That is specific enough to know what the tool produces. It does not, however, distinguish itself from near-neighbours like `capabilities` or `info`, so it falls short of a 5.

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

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

Passing `op` versus omitting it is implied by 'one operation, or of all operations', but the description never states when to reach for this tool over `capabilities` or `info`, nor any exclusions. Usage is inferable rather than 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered, and the description adds genuinely new context: newest-first ordering and the fact that entries include undo status and restorable deleted paragraphs. It stops short of behavior an agent would want, such as pagination or store-vs-document scope.

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 sentence, front-loaded with the identity of the resource before the details of its contents. No filler, though the back half packs three separate facts without much structure.

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 no output schema, the description adequately conveys what comes back. However, it omits pagination (the `cursor` field, `limit` of 200) and the alternate-store read mode, which an agent would need to use the tool repeatedly and 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 only 60%, and the description says nothing about any of the five parameters. The `kind` enum (batch/restore/undo/open/purge), `limit`, and `cursor` carry no description in either the schema or the text, so the description does not compensate for the coverage gap.

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

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

States a specific resource — the undo log — and its ordering (newest first), plus what each entry holds (what changed, whether undone, deleted paragraphs). It implies a relationship to `restore` but never names the sibling list tools (`history_search`, `history_orphans`) it must be distinguished from, so it stops short of a 5.

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

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

The description implies the tool is for reading the write/undo log, but gives no explicit when-to-use guidance, no when-not, and no routing to alternatives such as `history_search`, `revisions_list`, or `restore` as separate calls. An agent must infer usage entirely.

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

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

Annotations declare readOnlyHint=true, and the description adds a genuinely useful behavioral fact beyond that: orphaned history is never deleted automatically. It also names the two follow-up operations, so the agent understands the lifecycle. Missing are any return-shape or volume details, but the read-only safety profile is already covered.

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

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

Two sentences, tightly front-loaded with the resource definition before the follow-up actions. Every clause carries information: the scope, the lifespan fact, and the two possible next steps.

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

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

For a single-optional-parameter, read-only listing tool with no output schema, the description covers purpose, lifecycle behavior, and next actions. It is nearly complete; only a hint about what the list entries contain (beyond 'stores') would round it 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 `dir` parameter and its "Also scan this folder" semantics are already documented. The description's mention of `dir`/.doc-control loosely reinforces that scanning scope, but adds no syntax or format detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb ("List") and a precisely scoped resource ("stores whose document is gone"), then clarifies the jargon with examples (app-data stores, `dir`/.doc-control). This clearly distinguishes it from siblings like history_list and history_search, which operate on live document history rather than orphans.

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 for when to reach for it (finding history that outlived its document) and routes next steps (restore vs. purge). It stops short of explicitly contrasting when to use this over history_list/history_search, and the referenced `store` doesn't cleanly match the `restore` sibling, leaving a small inference gap.

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, which the description is consistent with ('Remove'). The description adds genuinely useful context beyond that: the operation is destructive but partial (a tombstone remains), and it requires a two-phase dry_run/confirm flow. It does not state whether the purge is reversible or what permissions are needed, keeping it short of 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?

Two sentences, zero padding. The destructive action and its scope lead, followed immediately by the safety workflow, so the most important information is front-loaded.

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

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

For a zero-required-parameter, six-param mutation tool with no output schema, the description covers the action, the scope options, the tombstone outcome, and the required dry-run workflow. Minor gaps remain (e.g., what the tombstone means for later reads, how doc/store interact), but an agent can call it safely as written.

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 six parameters (all, doc, store, before, confirm, dry_run). The description adds only the confirm-comes-from-dry_run linkage, which the schema also states. Baseline 3 is correct when the schema carries the parameter semantics.

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

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

States a specific verb and resource ('Remove undo history') plus its two scoping modes (all, or before a date) and the privacy intent, which is far more than a restatement of the name. It does not explicitly name the adjacent siblings it could be confused with (undo, restore, history_list/history_search), so an agent must infer the distinction from the verb alone.

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 operational workflow: 'Run with dry_run first, then repeat with its confirm.' This tells the agent both the required sequence and the gating mechanism, leaving nothing to inference for a destructive operation.

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=true, so the description carries most of the behavioral load and does surface real traits: exact-by-default matching, how match_level folds results, and the returned offsets/level structure. It omits things like ordering or performance caveats but adds genuinely useful behavior beyond the annotation.

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

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

Dense but front-loaded, with the purpose stated first and the matching/return behavior appended. It is appropriately short for a search tool, though the heavy backtick and clause structure may cost readability.

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

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

With 7 params, no output schema, and 57% coverage, the description should do more. It sketches the return shape (offsets, level, matches_by_level) but leaves the interaction of ignore_case/ignore_accents with folded levels only partially explained, so an agent still has blind spots.

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 a middling 57%. The description reinforces what match_level does to the result set, but that same detail already lives in the schema's rich match_level description, and it adds nothing for ignore_case, ignore_accents, limit, store, or doc. Marginal added value over 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+resource, 'Find a quote in the undo log,' and narrows the scope to the requests plus the paragraph text before/after each write. This clearly tells an agent it searches history rather than the live document, though it never names the sibling (e.g. find) it should be chosen over.

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

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

The description explains matching behavior but gives no when-to-use or when-not guidance and does not mention alternatives such as find, locate, or history_list. An agent must infer from the name alone that this is the history-search tool rather than the document-search tool.

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

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

With only readOnlyHint=false available, the description carries substantial extra context: the insert is done as tracked insertions, the field is left marked dirty so fields.update will not populate it, and Word requires F9 to build entries/page numbers. It also states the return value, all of which goes well beyond the annotation.

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

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

Front-loaded with the action and efficient overall; the middle sentence about the dirty field is dense but earns its place as essential behavioral context. No filler.

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

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

For a mutating tool with no output schema, the description covers what gets created (tracked insertions), how the field behaves, and what it returns. Minor gaps remain (e.g., permissions or reversibility), but it is largely complete.

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

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

Schema description coverage is 86%, so the schema already documents most parameters (doc, after, title, author, tag, dry_run, expect). The description adds workflow meaning around the field/title behavior but little parameter-specific syntax beyond what the schema provides, 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 ('Insert an index (an INDEX field) after a body paragraph'), and the reference to index.mark marks differentiates it from the sibling entry-marking tool. An agent can tell what it produces (a field plus title and closing paragraph) 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?

The mention that Word builds entries and page numbers 'from the index.mark marks (F9)' implies the prerequisite workflow with the sibling index_mark, giving clear context. It stops short of an explicit 'use this after marking entries / not for X' statement, so it's clear-but-not-exhaustive rather than full 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?

Annotations only declare readOnlyHint=false. The description adds meaningful behavior beyond that: the mark is written as a 'tracked insertion' (a tracked change, explaining the author/tag parameters) and produces an XE field that Word later compiles. This is useful mutation context, though it omits permission/undo 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?

Three short sentences, front-loaded with the core action and with no wasted filler. Minor awkwardness in the final clause, but overall tight and well-ordered.

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 no output schema and 7 parameters (86% schema coverage, nested expect object), the description covers purpose, entry format, and the relationship to index_insert. It does not address auth/revision-author requirements or how dry_run/expect behave, but the rich schema fills most remaining gaps.

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

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

Schema description coverage is already 86%, so the schema carries most parameter meaning. The description adds one nuance beyond the schema ('up to three levels' for entry depth), but does not clarify tag, author, expect, or dry_run beyond what the schema already states. 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+resource ('Mark an index entry: an XE field') and clarifies the mechanism ('tracked insertion, right after a range'). It also distinguishes itself from the sibling index.insert by explaining that index.insert builds the index from these marks.

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 relationship to index.insert is mentioned ('index.insert puts the index, which Word builds from the marks'), which implies the two-step workflow. However, it never explicitly states when to use index_mark vs the alternative, nor any prerequisites (e.g., that a document must be open). Usage is implied rather than instructed.

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

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

The readOnlyHint=true annotation already establishes this is a safe, non-mutating read. The description adds value by enumerating what it reports (hash, paragraph count, part existence), which is the closest thing to a return-value contract given there is no output schema, but it omits format, cost, and whether it processes the file eagerly.

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 short, front-loaded sentence with a leading label and no wasted words. It is efficient, though the trailing phrase 'which parts exist' is cryptic enough that the terseness costs some precision.

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

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

With no output schema, the description carries the return-value burden and does list the headline fields, which is adequate for a one-parameter read-only tool. It remains incomplete on the shape of 'properties' and 'which parts exist', and gives no hint about output structure.

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 a single parameter and schema description coverage is 100% ('Path to the .docx.'), so the schema fully documents the input. The description adds nothing about the parameter (e.g., relative vs absolute paths, file size limits), 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?

The fragment 'File facts' names the resource and enumerates the contents (size, hash, paragraph count, properties, part existence), so the agent can infer it reads document metadata. However, there is no verb and no differentiation from clearly overlapping siblings such as stats, outline, or paragraphs_list, which also report document-level facts.

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

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

The description gives no when-to-use guidance, no prerequisites, and no indication of when to prefer this over stats or paragraphs_list. The agent must guess whether 'info' or 'stats' is the right entry point for document metadata.

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 carry only readOnlyHint=false, so the description bears the full burden and delivers: tracked-change semantics, the all-or-nothing write contract (result plan must equal the request or nothing is written), refusal modes (UNSUPPORTED_CONTENT for pending tracked changes), inheritance rules for headers/footers, and untracked-only operations. This is unusually rich behavioral disclosure.

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

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

The size is defensible for a genuinely complex tool, but structure is poor: a single overloaded first sentence followed by long nested parentheticals makes the constraints hard to parse. It is front-loaded in intent but buries key rules (tracking, refusal) mid-parenthesis.

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

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

For a 7-parameter mutation tool with no output schema, the description covers refusals, tracking constraints, inheritance, and the all-or-nothing guarantee, which is substantial. It stops short of confirming exactly what dry_run returns or the success response shape, a minor gap given no 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 86%, so the baseline is 3, but the description adds real semantic meaning beyond the schema: {PAGE}, {NUMPAGES}, {chapter} become fields, null drops a section's own header/footer to inherit the previous one, break types are enumerated, and dry_run's listing behavior. This meaningfully deepens the plan and untracked semantics.

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

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

States a specific verb and resource — bring the document to a page plan — and anchors the format to a sibling ('as layout.get returns it'), which cleanly separates this write tool from layout_get. An agent can identify it 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?

It gives clear operational context: omitted keys are left unchanged, shown keys are checked not set, dry_run previews, and untracked: true is required for changes Word cannot track. It does not spell out a clean when-not-to-use or explicitly name layout_get as the read alternative, but the conditions are well signposted.

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?

readOnlyHint=true already covers the safety profile, so the description is free to add value, and it does: it discloses that undefined header/footer kinds are returned as null (inherited) and that the plan carries a "version": 1. That inheritance and versioning detail is non-obvious behavioral context an agent would otherwise have to discover empirically.

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 but well-ordered paragraph that front-loads the resource ("The document's page plan") before enumerating contents. Every clause carries information; nothing is padded, though the enumeration is slightly list-like in prose 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 no output schema, the description carries the burden of describing the return value, and it does so thoroughly: section structure, header/footer kinds, null inheritance, field placeholders ({PAGE}, {NUMPAGES}, {chapter}), and a version marker. Only the relationship to sibling layout/section tools is left unexplained.

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 parameter (doc) is documented as "Path to the .docx." The description adds nothing further about the parameter, 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?

The description clearly identifies the resource as "The document's page plan" with a precise enumeration of what it contains (section starts, breaks, page numbering, title page, header/footer per kind). It is a noun-phrase rather than an explicit verb, and it does not distinguish itself from siblings like layout_apply or sections_list, but an agent can tell this is a read of layout data.

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?

There is no guidance on when to use layout_get versus layout_apply or sections_list, nor any prerequisites (e.g. whether the .docx must be open). The description only says what the tool returns, not when to reach for it.

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 only readOnlyHint=false available, the description usefully discloses the failure/requirement condition around unsaved changes and the two escape hatches, information not present in the annotations. It still omits what happens if neither flag is supplied (error vs. silent no-op) and whether the call is idempotent.

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

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

A single sentence with the core action front-loaded and the edge case in a trailing clause; every word carries information and nothing is padded.

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 four-parameter tool with no output schema and minimal annotations, the description covers the essential action and the one tricky branch. Remaining gaps (acknowledgment that `doc` must reference an already-open document, error behavior) are minor.

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 by framing `save` and `discard` as conditional alternatives that only matter when there are unsaved changes — a relationship the schema does not encode. It does not clarify the `engine` parameter, which is already self-documenting.

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 gives a specific verb and resource ('Close the open document'), which is unambiguous on its own and hard to confuse with live_open or live_save. It does not, however, explicitly distinguish itself from any named sibling, so it stops short of the top band.

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 conditional requirement that unsaved changes need `save` or `discard`, which is useful invocation guidance, but it never says when to call this tool versus alternatives (e.g., live_save first, or undo) or when not to close. Usage is implied rather than 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?

Annotations only declare readOnlyHint=false, which is minimal. The description usefully discloses the two distinct outcomes — attaching to an existing window versus launching/opening one — which is genuine behavioral context beyond the annotation. It stops short of describing side effects of launching an external application, failure modes when the app is absent, or whether the attached session persists.

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

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

A single front-loaded sentence with no filler or redundancy; the attach-or-open duality is stated first. It is arguably under-specified rather than verbose, so it loses a point only for leaving gaps the reader must fill.

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?

Four parameters, no nested objects, and full schema coverage mean the schema carries the parameter burden, and there is no output schema to describe. However, for a stateful tool that manipulates an external application, the description omits prerequisites, launch-versus-attach preconditions, and failure behavior, leaving it only minimally adequate.

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

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

Schema description coverage is 100% and the schema explains `app`, `doc`, `front`, and `engine` thoroughly, including that `front` reflects whether the window actually came forward. The description adds no parameter detail 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 dual behavior: attach to an already-running app window, or open the document in a live app. That is a real verb+resource with scope (a 'live app' session). It does not, however, distinguish itself from the sibling `open`, so an agent cannot resolve which of the two to pick from the text alone.

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?

There is an implicit scenario ('the app window holding the document'), but no explicit when-to-use guidance, no prerequisites (e.g., that a live app session must exist or be launched), and no named alternative such as `open`. The agent must infer routing from the tool name against ~60 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 declare readOnlyHint=true, so safety is covered. The description adds genuinely useful context beyond that: the buttons trigger live.select on click in MCP Apps clients and bypass an assistant turn. It does not describe what the tool returns to the model or what happens in clients that don't render apps, which keeps it below 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?

A single front-loaded sentence that leads with what is rendered and then the click behavior. No filler, 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?

With no output schema and full schema coverage on inputs, the description covers the essential behavioral twist (UI buttons, no assistant turn). Minor gaps remain around fallback behavior in non-App clients and interaction with the mode parameter, but nothing critical 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 nested places object is fully documented in the schema, so the description adds little parameter detail. Its only contribution is loosely tying the click action to select-style behavior, which the schema's mode enum already spells out precisely.

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 concrete verb and resource ('show a list of places as buttons') and explains the interaction payoff (a click calls live.select with no assistant turn), which distinguishes it from live_select and locate. It stops short of naming those siblings explicitly, so the differentiation is implied rather than guaranteed.

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 phrase 'in a client that renders MCP Apps' implicitly scopes when this tool is useful, but there is no explicit when-to-use, when-not-to-use, or alternative (e.g. use live_select directly for non-UI clients). Usage 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?

The readOnlyHint=false annotation already tells the agent this is a mutating operation, so the bar is lower. The description adds the useful detail that saving happens inside the live app rather than writing a path, but is silent on overwrite behavior, error cases when the doc isn't open, or what is returned.

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

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

A single front-loaded sentence with no filler. It is efficient, though arguably terse enough to border on under-specification.

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 no output schema and minimal annotations, the description should clarify prerequisites (an already-open document) and failure behavior. As written, an agent lacks enough behavioral context to call it confidently.

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 the 'doc' and 'engine' parameters are already documented in the schema. The description adds no syntax or format detail beyond that, 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 open document'), and the phrase 'in its app' signals it targets the live-app integration rather than a file path. It does not explicitly differentiate from siblings like live_open or live_close, so it falls short of a 5.

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

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

There is no guidance on when to use this versus alternatives such as live_open, live_close, or a file-based open/save. No preconditions (e.g., document must already be open in a live app) are stated.

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

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

Annotations carry readOnlyHint=false, so the agent already knows this is not a pure read, and the description's 'Select a paragraph in the app's window' is consistent with that. However, it never discloses the real side effect - that it changes the app's current selection/cursor and may bring the window to the front - although the schema's `mode` and `front` descriptions partially cover the latter. Adds modest context beyond annotations; no contradiction.

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

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

A single well-formed sentence that front-loads the action, both selection mechanisms, and the return value, with zero filler. Nothing needs trimming and nothing essential is buried.

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?

There is no output schema, and the description sensibly states what comes back ('its text and address'), which is the key missing piece. With nine parameters at full schema coverage and enums carrying the behavioral detail, the remaining gap is the undisclosed effect on the live app's selection state.

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 four enums are fully documented, so the baseline is 3. The description adds only a shallow hint ('by address (`at`) or by a `locate` find phrase') and even refers to `locate` rather than the actual `find_phrase` parameter, so it contributes little beyond the schema.

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

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

Specific verb (select) plus resource (a paragraph) and scope (in the app's window), with the two addressing mechanisms (address or find phrase) named. It is clear what the tool does, but it never names or contrasts with near siblings like para_get, locate, find, or live_selection, so sibling differentiation is left to inference.

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 sentence implies the two ways to identify a paragraph (`at` vs a locate find phrase), but gives no when-to-use or when-not guidance and no comparison to alternatives such as locate, find, para_get or live_selection. An agent must infer when selecting in the live app is preferable to just reading text.

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=true, so the bar is low and the safety profile is already covered. The description usefully discloses what content comes back (selection plus cursor paragraph), which matters since there is no output schema. It omits behavior when nothing is selected or no live app is attached, so it adds some but not rich 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?

A single sentence with no filler, and it leads with the primary return value. It is efficient, though arguably under-specified for a tool with no output schema rather than genuinely concise.

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

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

With no output schema, the description must carry the return-value burden, and it does describe the returned content. However, it leaves out edge cases (empty selection, missing live session) and any prerequisite context, which a low-complexity read tool would benefit from stating.

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 'doc' and 'engine' are fully documented in the schema itself, including the enum restriction. The description adds no parameter-level meaning beyond that, so the baseline of 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?

The description clearly identifies the resource returned: the current text selection plus the containing paragraph. It is a noun-phrase description of output rather than a verb+resource action, and it does nothing to distinguish itself from siblings like live_select or para_get, but an agent can understand what data this yields.

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?

There is no guidance on when to call this versus live_select, live_status, live_places, or para_get. No prerequisites (e.g. a live app must be open with a document) and no exclusions are stated. The agent must infer usage entirely from the name.

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?

readOnlyHint=true already tells the agent this is a safe, non-mutating read, so the bar is lower. The description does add real behavioral context beyond the annotation: it reports reachability of live apps and flags unsaved changes. It says nothing about probe latency or what happens when no live app 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?

A single dense sentence with the primary function (live apps reachable) front-loaded before the `doc` refinement. Slightly fragmentary wording ('Live apps ... and the documents they have open') 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?

For a two-parameter, zero-required, read-only discovery tool with no output schema, the description covers both the app-level and document-level results, including the unsaved-changes signal. Missing only edge-case behavior such as empty results and whether reachability checks are slow or best-effort.

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%, including a clear `doc` description and an enum-note for `engine`, so the schema does the heavy lifting and baseline 3 applies. The description's mention of `doc` (which app has it open, full path, unsaved flag) explains the returned detail rather than adding new input semantics.

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

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

The description states the resource specifically: enumerated live apps (Word, LibreOffice) that are reachable, plus the documents they hold open. It is clearly distinguishable in substance from mutation siblings like live_open/live_close/live_save, though it never names any of them to say how it differs from live_places or live_selection.

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?

There is no explicit statement of when to call this versus the many live_* siblings (live_places, live_selection, live_save). The only conditional guidance is implicit in how the optional `doc` argument narrows the result, which is parameter behavior rather than tool-selection guidance.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds that output is paged (one, a range, or the whole document) and enumerates what is returned, which is useful behavioral context, but it says nothing about cost, permissions, or ordering.

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 a single dense sentence with no padding, so it is compact, but the run-on phrasing ('plus a phrase Word's Find meets once (one, a range, or the whole document, paged)') is hard to parse and the key action is not front-loaded.

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

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

This is a 7-parameter tool with a nested detection-profile object, an overrides array, and no output schema, yet the description explains none of the structural-detection behavior or the profile knobs. For a tool of this complexity, reliance on schema text alone leaves the agent without a mental model of what it will get.

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 nested profile object is thoroughly documented in the schema itself. The description adds no parameter meaning beyond that, so the baseline 3 applies rather than a penalty.

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 does convey a specific output: per-paragraph chapter/scene/page plus a unique anchor phrase, and a Find-matching phrase, paged. But it reads as a list of return values rather than a stated action, and the vague name 'locate' is never tied to a resource. It is distinguishable from siblings only by inference, not by explicit statement.

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?

There is no when-to-use or when-not-to-use guidance at all. Siblings like paragraphs_list, outline, find, and page_estimate overlap heavily with this tool's output, and the description never says which situation selects locate over them.

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 lone readOnlyHint=false annotation: it discloses that the reference mark and note text are tracked insertions, that rejecting them removes the note, that the notes part is created if absent, and what the call returns. Permission/author requirements and side effects on existing notes are not covered.

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 action and anchor, then the undo semantics, then the return value. No filler and nothing buried.

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

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

With no output schema, the description helpfully states the returned id, displayed number and address, and it explains the notes-part creation. Coverage of the optional parameters (tag, author, expect) is left entirely to the schema, a minor gap for an 8-parameter mutation tool.

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

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

Schema coverage is 75%, so most parameters (at, text, doc, dry_run) are already documented. The description reinforces the anchor semantics ('mark goes after the offset') and the one-line note text but says nothing about tag, author, or expect, adding only marginal meaning.

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 (Add) plus the two resource types (footnote/endnote) and the anchoring mechanism (body offset), which clearly separates it from siblings like xref_add, caption_add, or comments_list.

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?

Implies when it applies (adding a note at a body point) and constrains the anchor via 'at', but never names an alternative tool or states exclusions, so an agent must infer routing from the sibling list.

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

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

With only readOnlyHint=false available, the description adds substantial behavioral context: a backup is written to a store, retention applies, a history entry is created, and the document content is left unchanged. This meaningfully expands on the single annotation, though it doesn't cover failure modes or what the return looks like.

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

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

The action is front-loaded and the whole definition is two compact clauses plus a short clarifying sentence. Every element earns its place, though the parenthetical '(retention applies)' is slightly terse.

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

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

For a single-parameter tool with no output schema and a minimal annotation, the description covers the side effects, the retention implication, and the timing trigger adequately. The main remaining gap is disambiguation from sibling tools like live_open and restore.

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 with 100% schema description coverage ('Path to the .docx'), so the schema already carries the semantics. The description references 'the document' but adds no format or path guidance beyond what the schema states, matching the baseline for fully 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?

The description concretely states what the tool does: it backs the document into its store (with retention) and records an entry in the history, clarifying that the document itself is not modified. This is specific enough to distinguish it from a generic 'open', but it never contrasts with the near-identical sibling live_open or restore, leaving real ambiguity about which 'open' to pick.

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 an explicit trigger: 'call it when a session starts,' which tells the agent the scenario in which the tool is appropriate. It stops short of naming exclusions or alternatives (e.g., live_open), so the agent gets context but no 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?

The readOnlyHint annotation already establishes this is a safe read, so the description's main added value is the 'in order' ordering guarantee, which is not derivable from the schema. It says nothing about pagination behavior, the ~8,000-byte cap, error conditions, or how 'address' values are formed, so behavioral coverage beyond annotations is thin.

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 tight fragment with zero filler, and the returned fields are front-loaded. It is arguably under-specified rather than padded, but as a matter of size and structure it is efficient and readable.

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

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

There is no output schema, so the description carries some burden for explaining the return payload, and it does name the returned fields. But for a five-parameter, paginated tool with a stories mode, it omits the pagination/cursor continuation flow, the byte cap, and the address format, leaving real gaps.

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

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

Schema description coverage is 100% (limit, cursor, stories, max_level are all documented in-schema, including the stories prefix format). The description adds nothing about parameters, so the baseline of 3 applies; the mention of 'level' loosely hints at max_level but adds no new semantics.

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

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

The fragment identifies the resource (document headings) and the fields returned (level, style, address), which lets an agent infer this is the outline/heading-extraction tool rather than a paragraph or section lister. However, it never states an action verb ('list', 'extract', 'return'), so the purpose is implied rather than asserted, and there is no explicit contrast with siblings like paragraphs_list.

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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as paragraphs_list or toc_insert. The agent must infer usage purely from the tool name and the noun phrase describing the output.

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=true, so the description carries most of the burden and it does well: it discloses the estimation method (rendered page marks and explicit breaks take precedence, word-count model as fallback) and warns that every value is `estimated: true`. It doesn't note precision limits or pagination behavior, but the methodology disclosure is the key behavioral fact.

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

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

Two tight sentences, front-loaded with the output subject and followed by the method caveat. Nothing is padded.

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 5-param read-only tool with no output schema, the description covers what is returned, how it is computed, and its reliability caveat. Cursor/limit semantics are left entirely to the schema, which documents them, so nothing critical 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% with example addresses and limits already documented, so the baseline is 3. The description's parenthetical echoes the `at`/`by` distinction but adds no syntax or format detail beyond the schema.

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

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

The description states a specific resource (page position of paragraphs) and scope ('each paragraph (or of one)'), enough to distinguish it from paragraphs_list or stats. It reads slightly as a field label rather than a full verb, but the intent is unambiguous.

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

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

No when-to-use guidance or alternatives are named, despite siblings like paragraphs_list, stats, and locate being plausible substitutes. The 'or of one' hint implies the `at` filter but never says when to prefer the single-paragraph mode.

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

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

With readOnlyHint:true, the safety profile is clear. The description adds some behavioral context by detailing what is returned (text, style, formatting, layout) and clarifying the heading_level semantics. However, it doesn't disclose pagination behavior despite having limit and cursor parameters, nor does it mention performance or authorization 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?

The description is a single, front-loaded sentence that packs in the return payload and a key semantic detail (heading_level values). It is efficient, though the parenthetical could be slightly clearer.

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 tool with no output schema, the description gives a good sense of returned data but omits pagination behavior (limit/cursor) and input prerequisites (e.g., obtaining 'at' from a prior read). These gaps mean an agent might misunderstand how to retrieve large paragraphs or where the address comes from.

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, including the 'at' address format and pagination cursor/limit. The description adds no additional parameter meaning, so baseline 3 is appropriate.

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

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

The description states a specific verb ('get') and resource ('one paragraph by address') and enumerates return contents (text, style, direct formatting, formatted spans, layout facts). This distinguishes it from paragraphs_list and other siblings, though it could be more explicit that it retrieves information for a single paragraph.

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

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

There is implied usage: it requires a paragraph address ('at'), which suggests it's used after a read result. However, the description doesn't state when to use this tool versus paragraphs_list or table_get, nor does it mention prerequisites or alternatives.

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

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

readOnlyHint=true already declares the safe-read profile, so the description's added value is limited to ordering ('document order') and the heading_level null semantic for body paragraphs. It says nothing beyond the schema about pagination or the ~8,000-byte cap, which schema already carries.

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

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

Two tight sentences that front-load the core promise (every paragraph with its facts) before the optional add-ons. Every clause carries information, though the final heading_level sentence is a minor output detail tacked on.

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

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

With no output schema, the description usefully enumerates the returned fields (address, text, style, layout facts, normalized, page) and their semantics. It is reasonably complete for a list tool, with pagination left entirely to the cursor parameter's schema text.

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 fully documents all six parameters. The description only loosely mirrors the optional normalized and pages behavior and introduces heading_level, which is an output field rather than a parameter; it adds little parameter-level meaning beyond 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 resource (every paragraph) with its returned fields (address, text, style, layout facts) and scope (document order). An agent can tell this is a bulk enumeration rather than a single-item fetch, though it never names the sibling para_get as the alternative for one paragraph.

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

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

Usage is only implied by the word 'Every' and 'in document order' – the natural read is 'use this to enumerate all paragraphs.' There is no explicit when-to-use/when-not guidance and no routing to para_get for targeted lookups, leaving the agent to infer the boundary.

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?

readOnlyHint=true already tells the agent this is a safe read. The description adds one useful behavioral detail beyond the annotation: invalid recipe files are still returned rather than causing a failure. It says nothing about ordering, caching, or completeness of the listing.

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

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

A single sentence with the key verb front-loaded and no filler. Every clause (bundled, user, invalid files) carries information about what is returned.

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

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

For a zero-parameter, read-only list tool the description is nearly sufficient: it enumerates the categories returned, including the error case. With no output schema, it could say more about the returned entry shape, but complexity here is very low.

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

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

The tool takes zero parameters, so per the baseline this scores 4. The description correctly implies no filtering or argument options exist.

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 gives a specific verb and resource ("List ... recipes") and narrows scope to bundled, user, and invalid recipe files, which is more than a name restatement. It does not explicitly contrast with the obvious sibling recipe_run, so the distinction is inferred from the verb rather than stated.

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

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

Usage is only implied by the verb: an agent can infer this is the read/inspect counterpart to recipe_run. There is no explicit when-to-use, no exclusion, and no named alternative, so guidance stays at the implied level.

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

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

The description usefully discloses the fixpoint behavior ("repeated until stable") and that application is a separate step. However, the schema's dry_run parameter states "recipe.run never writes," while the annotation declares readOnlyHint=false, so the safety profile the agent receives is internally inconsistent.

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

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

A single front-loaded sentence stating the action, its result, its iteration semantics, and the follow-up step. Every clause earns its place with no filler.

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

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

The description covers the call-and-apply workflow for a 4-parameter tool, but with no output schema it leaves the shape of the "batch proposal" undefined and never resolves whether the underlying document is touched during the run. Adequate but with real gaps for an agent deciding how to proceed after the call.

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 doc, recipe, dry_run, and definition are all documented in the schema; the description adds no parameter-level detail beyond the workflow reference to batch. Baseline 3 is appropriate when the schema carries parameter semantics.

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

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

Specific verb+resource (run a recipe) plus an explicit statement of what is produced (a batch proposal) and how it is consumed (apply with batch). It is unmistakably distinct from siblings recipe_list and batch, since it names batch as the applying step rather than doing the write itself.

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 the workflow context: run here to get a proposal, then apply with batch, which tells the agent this is a non-applying, proposal-generating step. It does not state exclusions, e.g., when to skip it and go straight to batch, or when to prefer an inline definition over a stored recipe.

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

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

Annotations only supply readOnlyHint=false; the description adds meaningful context that the restored content becomes a *tracked insertion* (a revision, not a silent write) and that omitting `change` restores every paragraph the op deleted. This goes beyond the annotation, though it does not disclose return values or the reversibility of the tracked change.

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?

Very short (two sentences) and front-loads the core action. The second sentence is a grammatical fragment ('Without `change`, every paragraph the op deleted'), which is efficient but slightly hurts 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?

For a 9-parameter mutation tool with no output schema, the description covers the core action and default scope but omits return behavior and how it interacts with revisions/history. High schema coverage compensates for undocumented params, so it is minimally adequate rather than 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 high (89%), which sets a baseline of 3, but the description genuinely adds meaning for `change`: the schema only says it is an index, while the description explains the default behavior when it is omitted ('every paragraph the op deleted'). Other parameters are left entirely to the schema.

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

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

The description states a specific verb and resource ('Bring a logged paragraph back as a tracked insertion'), so the agent knows this restores a previously deleted/changed paragraph. However, it never distinguishes itself from siblings like `undo`, `history_list`, or `history_search`, and the phrasing 'after the paragraph that holds its place now' is awkward to parse.

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

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

No explicit when-to-use guidance and no mention of alternatives (e.g., `undo`, `history_search`, `history_orphans`) despite several plausible siblings. The only conditional hint is buried in the parameter text ('needed when that place was edited'), which is not tool-level 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?

readOnlyHint=true already tells the agent this is a safe read, so the description's remaining job is small. It adds one genuine behavioral detail not in the annotations: results are returned 'in document order'. It says nothing about cost, pagination semantics, or whether unaccepted revisions are included, but does not contradict 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?

A single, dense sentence fragment that front-loads the resource and enumerates the returned fields with no wasted words. It is efficient, though it reads as a bare fragment rather than a front-loaded statement of purpose plus behavior.

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 lister with a 100%-covered schema, no output schema, and clear annotations, the description is nearly sufficient: it conveys the return shape so the agent knows there is no output schema to consult. The missing piece is usage/routing context relative to the many sibling list/search 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% – every parameter (doc, type, limit, author, cursor, stories) is already documented with a description in the schema, including pagination via cursor and the 8,000-byte cap. The description adds no parameter-level meaning, 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?

The description names a specific resource (tracked changes/revisions) and describes the returned fields (author, date, type, text, paragraph address), which is clearly distinct from siblings like comments_list, diff, or compare. It never states the verb 'list' explicitly nor names an alternative, so it stops short of 5, but the purpose is unambiguous.

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

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

There is no when-to-use guidance, no mention of prerequisites (e.g. must the document be open or unmodified?), and no routing to sibling tools such as history_list or comments_list. The agent must infer the use case purely from the tool name and the returned fields.

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?

readOnlyHint=true already tells the agent this is a safe read. Beyond that, the description adds no behavioral context: it doesn't say whether sections are returned in document order, whether it covers only a subset (e.g., not the body), or what happens with zero-section documents. The attribute enumeration is content, not behavior, so the description adds little beyond the annotation.

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

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

One tightly packed sentence with no filler; the attribute list is front-loaded. It is efficient, though the list-within-sentence construct makes it denser than ideal for scanning, which is a minor structural weakness.

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 a simple one-parameter read with a fully documented schema and a readOnlyHint annotation, the description covers what is returned but omits any framing (item count, ordering, relationship to the document body). It is minimally adequate for invocation but leaves the agent guessing about the return shape in the absence of an output schema.

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

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

Schema description coverage is 100% — the single 'doc' parameter is documented in the schema as 'Path to the .docx.' The description contributes no additional parameter meaning. When the schema fully documents parameters, baseline 3 is appropriate.

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

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

The description names the resource (each section's page setup) and enumerates the specific attributes returned (break type, title page, even/odd headers, page numbering, header/footer addresses). However, it never states the verb — that it lists/returns these for all sections — and it doesn't differentiate from siblings like layout_get or info, which could plausibly also return section-level layout data.

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?

There is no explicit when-to-use guidance, no mention of when NOT to use it, and no alternatives named. With siblings like layout_get, info, and styles_list, the agent has no signal for choosing this tool over those. Usage must be inferred from the name alone.

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

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

The readOnlyHint annotation already establishes a safe read operation, so the bar is lower. The description adds one meaningful trait — that ids are 'stable' (reusable across calls, e.g. for overrides) and that results carry 'detection signals' — but says nothing about pagination, the ~8,000-byte cap, or how detection signals are shaped.

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 a single terse fragment with no wasted words, but it is under-specified rather than well-structured — there is no front-loaded verb and the two halves are joined by an unexplained 'or'.

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?

This is a complex tool (9 params, nested profile, overrides) with no output schema, so the description should carry return-value information. It never explains what a 'detection signal' or a segment record looks like, nor how cursor/limit interact with the byte cap, leaving the output contract unexplained.

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 fully documents the 9 parameters including the nested profile object. The description adds no parameter syntax or semantics beyond implying the unit values, so baseline 3 is appropriate.

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

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

The description names the resources it produces (chapters, scenes, sentences, dialogue lines) and distinguishes them via 'stable ids and detection signals,' but it is a noun fragment with no explicit verb — the agent must infer that it lists/segments a document. It also fails to differentiate itself from plausible siblings like outline, paragraphs_list, or sections_list.

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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives. The agent is left to guess whether this or outline/sections_list is the right tool for a given segmentation need.

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?

readOnlyHint=true already establishes the safe read-only profile, so the description is not the sole carrier of behavioral information. It adds which metrics are computed, but says nothing about scope of counting (e.g. whether it covers the whole package or only the body), performance, or result shape.

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

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

A single front-loaded sentence with no filler; every listed item is informative and nothing is 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 simple read-only counting tool with 100% schema coverage and an annotation confirming read-only behavior, the description is sufficient; the enumeration of counted items effectively signals what comes back even without an output schema. Only the counting scope is left unstated.

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 'doc' path and the 'stories' enum semantics are fully documented in the schema itself. The description contributes no additional parameter meaning, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb ('Counts') plus an explicit enumeration of the resources counted (paragraphs, words, headings, tables, comments, revisions, fonts, styles). An agent can distinguish it from list-style siblings like paragraphs_list or revisions_list, though it does not explicitly contrast with the nearby 'info' tool.

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

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

Usage is only implied by the enumeration: an agent infers it is the tool for aggregate document metrics. There is no explicit when-to-use statement, no exclusions, and no pointer to alternatives such as info or page_estimate.

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, confirming this is a write. The description adds nothing beyond that: it doesn't say what is created, what happens if the id/name already exists, that dry_run previews, or that the styled doc is modified on disk. With a mutation tool and nested formatting objects, the one-phrase description leaves the behavioral burden entirely on the schema.

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 three-word sentence with zero waste and the action front-loaded, but it is terse to the point of being uninformative for a 14-parameter tool. Concise, not padded, yet barely a sentence.

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 14-parameter mutation tool with nested run/paragraph objects, enum-driven type selection, an expect/sha256 guard, and no output schema, the description is far too thin. It omits style kinds, formatting semantics, and any mention of the dry_run/expect safety mechanisms the schema exposes.

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 93%, so nearly all 14 parameters (id, run, paragraph, based_on, link, next, type, dry_run, expect, etc.) are already documented in the schema. The description contributes nothing extra, 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?

"Add a style" merely restates the tool name style_create (verb+resource) without adding meaning — it does not clarify what a 'style' is in the docx model or what distinguishes this creation call from siblings like style_update, style_rename, or style_merge.

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

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

No when-to-use guidance at all. The agent gets no cue for choosing style_create over style_rename, style_update, style_merge, or styleset_import-dotx, and no prerequisites (e.g., the doc must be open or exist) are given.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description usefully adds that results include inherited formatting and heading level, but says nothing about behavior when the id/name is not found, whether name matching is case-insensitive, or how inheritance is resolved.

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

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

A single front-loaded sentence with a colon-separated list of returned fields and zero filler. It is a sentence fragment rather than a full clause, but nothing is wasted and the key scoping word 'One' leads.

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

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

For a two-parameter read tool with no output schema, the description does cover the main return content (own formatting, inherited formatting, heading level), which is what an agent most needs to decide whether to call it. Gaps remain around failure behavior and inheritance resolution, but the core is present.

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 there (doc = path to the .docx, style = style id or name). The description's 'by id or name' merely restates the schema and adds no extra syntax or format guidance, 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 (get) and resource (style) with scope narrowed to 'One style by id or name', and enumerates what the result contains (own formatting, inherited formatting, heading level). This clearly separates it from the plural styles_list and from mutating siblings like style_update/style_rename, though it does not name any sibling explicitly.

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

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

Usage is only implied by the singular 'One style' phrasing: read a single style rather than the full set. There is no explicit when-to-use, no when-not-to-use, and no mention of the alternative (styles_list) or of prerequisites such as the document needing to be open.

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 provide only readOnlyHint=false, so the description carries most of the burden. It usefully discloses destructive behavior (the 'from' styles are removed) beyond what the annotation states, but omits the existence of a dry_run preview, the sha256 preflight expectation, and irreversibility/error handling. Solid but incomplete.

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 tight sentence with the destructive outcome front-loaded alongside the core action. No filler, though it is arguably too terse given the tool's destructive nature.

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

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

For a destructive mutation with no output schema and nested parameters, the description covers the core action but leaves out the dry_run preview path and the sha256 preflight, which matter for safely invoking a delete-style merge. Adequate but with clear gaps.

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

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

Schema description coverage is 80%, so the baseline is 3. The description adds the crucial relationship that 'from' styles are removed while 'into' is preserved, which clarifies the from/into semantics, but says nothing about 'expect', 'dry_run', or list handling for 'from' beyond what the schema already documents.

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 (re-point) and resource (styles) plus the merge semantics: uses of 'from' get redirected to 'into' and 'from' is deleted. This clearly distinguishes it from siblings like style_rename and style_update, which modify single styles rather than consolidating them. It doesn't name a sibling explicitly, so a 4 rather than a 5.

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

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

The merge semantics imply when to use it (consolidating duplicate/redundant styles), but the description gives no explicit when/when-not guidance and never points to alternatives such as style_rename or style_update. Usage is inferred rather than stated.

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

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

Annotations only supply readOnlyHint=false, and 'Change' is consistent with that. The description adds one genuine behavioral fact beyond the annotations: 'references follow', i.e. dependent references are updated when the id changes. It says nothing about the dry_run preview path or the expect/sha256 concurrency guard, which are the other notable behaviors.

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 compact sentence with the action front-loaded and no filler. It is arguably too terse for a mutation tool, but nothing in it 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?

No output schema exists, and the only annotation is readOnlyHint=false, so the description must carry the behavioral burden for a write operation with 6 parameters. It covers the key side effect (references follow) but omits collision/error behavior, dry_run semantics, and the expect-based pre-condition check.

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 high (83%), so the schema already documents id, doc, name, style, dry_run and expect. The 'and/or' phrasing is a small value-add, clarifying that name and id are independently optional, but the description adds little else about parameter interplay (e.g. id defaulting from name).

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 concrete verb and resource ('Change a style's display name and/or id'), so the agent knows exactly what is mutated. It does not differentiate itself from the sibling style_update, which plausibly also edits style properties, so a sibling-confusion risk remains.

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?

There is no explicit statement of when to call this instead of style_update, style_create, or style_merge, and no prerequisites (e.g. style must already exist). Usage is only loosely implied by the verb 'rename'.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description does add one useful behavioral detail beyond the schema: that the JSON is optionally persisted to a file via the `out` parameter. Since there is no output schema, more on the returned structure would have helped, but the note about the disk write is genuine added value.

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

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

A single terse sentence with no waste and the core outcome front-loaded. It is a noun fragment rather than a verb phrase, which slightly weakens the lead, but nothing is padded.

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 five parameters, a 100%-covered schema, and readOnlyHint annotation, the essentials are available elsewhere. The description still omits what the JSON style set contains, how filtering interacts, and any error behavior, leaving gaps for a tool with no output schema.

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

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

Schema description coverage is 100%, so all five parameters are documented in the schema and the baseline is 3. The description only echoes the `out` behavior and says nothing about `name`, `styles`, or `custom_only`, adding no meaning beyond the schema.

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

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

The fragment clearly conveys the action (extract the document's styles as a JSON style set) and the optional file output. However, it does not distinguish this from the sibling styleset_export-dotx (which presumably exports the same data in a different format) or from styles_list, so sibling differentiation is missing.

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?

There is no when-to-use guidance, no exclusions, and no mention of alternatives such as styles_list or styleset_export-dotx. The agent must infer the choice purely from the tool name.

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

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

The annotation readOnlyHint=false marks this as a write, and the description usefully clarifies that the write targets a new file and 'never touches the document' – a meaningful safety detail beyond the annotation. It does not disclose overwrite behavior when `out` already exists, required permissions, or error conditions.

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 tight sentence, front-loaded with the action and followed by the key behavioral constraint. 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?

For a file-export tool with full schema coverage and an annotation carrying the read/write signal, the description is nearly complete; the non-destructive constraint is stated. Minor gaps remain around overwrite semantics, but no output schema is needed since the result is a written file.

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 every parameter (doc, out, name, styles, custom_only) is already documented in the schema. The description adds no syntax or format detail beyond what the schema provides, 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 (write/export) and resource (the document's styles as a .dotx template), which is clear on its own. However, it does not differentiate itself from the sibling styleset_export, so an agent cannot tell from the description alone which export variant to pick.

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?

There is no when-to-use guidance and no mention of the alternative styleset_export or styleset_import-dotx. The agent is left to infer usage from the name and the sibling list, with only the 'never touches the document' clause hinting at the operation's nature.

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, so the description usefully fills the gap: it discloses that new styles are added, existing ones are replaced or skipped, and that dry_run writes nothing. This is meaningful mutation-behavior context beyond the annotation. It stops short of stating prerequisites, side effects on references, or reversibility.

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

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

A single tightly packed sentence: verb+resource first, then the effect on new/existing styles, then the dry_run qualifier. No filler, nothing repeated from the 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?

For a 5-parameter mutating tool with no output schema and a nested expect object, the description covers the main write semantics and dry_run but omits the sha256 integrity check, any return-value expectations, and any differentiation from styleset_install. Adequate but with visible gaps.

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

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

Schema description coverage is 80%, so the baseline is 3. The description does add meaning for on_conflict (its 'replaced (or skipped)' phrasing maps to the enum) and dry_run, but the expect/sha256 integrity parameter is untouched and doc/path are left to the schema.

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

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

The description states a specific verb and resource: installing .dotx template styles into a document, with concrete effect details (new styles added, existing replaced or skipped). It is clear what the tool does, but it never distinguishes itself from the sibling styleset_install, which an agent could easily confuse it with.

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?

There is no explicit guidance on when to use this tool versus styleset_install, styleset_export-dotx, or style_merge. The conflict-resolution and dry_run semantics are described, but those are behavior, not selection criteria, so the agent must infer when this tool is the right choice.

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 supply only readOnlyHint=false, so the description carries the real burden and delivers: new styles are added, existing ones replaced or skipped, and dry_run writes nothing. That is genuine mutation/overwrite disclosure beyond the annotation. It omits permission needs, failure/rollback behavior, and the effect of on_conflict='error'.

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

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

A single front-loaded sentence with a colon and a parenthetical; the write semantics come first and the dry_run caveat last. 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?

For a 6-parameter mutation tool with nested objects and no output schema, the core behavior is covered but key gaps remain: the expect.sha256 integrity check, the relationship/mutual exclusivity of doc, path, and inline styleset, and the third on_conflict mode are all unexplained.

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 83%, so the schema already documents doc, path, dry_run, styleset, and on_conflict. The description echoes the conflict resolution and dry_run semantics but adds no new detail, and is silent on the nested expect.sha256 verification and the 'error' enum value.

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

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

The description states a specific verb (Install) and resource (a JSON style set into the document), and the 'JSON' qualifier implicitly separates it from the dotx-oriented siblings styleset_import-dotx/styleset_export-dotx. It does not name any sibling explicitly, but the scope is unambiguous.

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

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

It never states when to use this versus style_create, style_update, styleset_import-dotx, or style_merge, nor any prerequisites (open document, valid style set). The only usage signal is the incidental 'dry_run previews' clause, which is inferential rather than directive.

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?

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds the useful fact that per-style usage counts are returned, but says nothing about ordering, pagination mechanics, or the byte cap beyond what the schema already states.

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 compact sentence with no filler, and the core resource is front-loaded. The trailing phrase "with how many times each is used" is slightly awkward but it is the one piece of output information the schema cannot convey.

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

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

With no output schema, the description carries the burden of describing the return, and it does so only partially (styles plus usage counts, but not ordering or field shape). Combined with the absent usage guidance for a five-parameter list tool, it is adequate but incomplete.

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

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

Schema description coverage is 100% and each parameter already documents itself, including the cursor continuation value and the 8,000-byte response cap. The description adds no parameter-level meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific resource (styles defined in the document) and an output attribute (usage counts), which is more than a restatement of the name. It does not, however, distinguish itself from siblings like style_get or styleset_export, so the agent must infer the boundary.

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

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

There is no when-to-use guidance, no contrast with style_get (single style), style_create, or styleset_export, and no mention of prerequisites. The agent gets no help deciding between this and neighboring style tools.

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

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

The only annotation is readOnlyHint=false, so the description carries the full burden of behavioral disclosure. It says nothing about the existence of a dry_run preview, the sha256/expect concurrency guard, whether omitted keys are left untouched, or that null removes a key. For a mutation tool with near-zero annotation coverage this is a meaningful gap.

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

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

A single front-loaded sentence that names the verb, the target and the changeable facets with no filler. Efficient, though it is arguably too terse for a 10-parameter mutation tool.

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 10 parameters, nested objects, no output schema and only a readOnlyHint annotation, the description is thin: it never mentions dry_run preview, the expect/sha256 optimistic-concurrency check, or that doc is a required .docx path. An agent could invoke it but would miss safety-relevant behavior.

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

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

Schema description coverage is 90%, so the schema already documents doc, run, link, next, quick, based_on, paragraph, dry_run and expect. The description echoes the field groups but adds no syntax, format or precedence detail beyond what the schema provides; 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?

Clear verb (Change) plus resource (style) and enumerates the mutable facets: parent, next/link styles, quick flag, formatting. An agent can tell it apart from style_create or style_rename. It stops short of explicitly naming those siblings as alternatives.

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?

There is no when-to-use guidance and no mention of the obvious alternatives in the sibling list (style_create for new styles, style_rename for renaming, style_merge for consolidation). The agent is left to infer that this tool only mutates existing styles.

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=true, so the description carries most of the behavioral burden and does so well: numbering rules for nested tables, the fact that an empty w:tbl still consumes a number, and story-scoped numbering. It adds no error or failure semantics (e.g., what happens for an out-of-range table number), which keeps it from 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?

Two dense sentences with no filler; the return shape is front-loaded and the numbering rules follow immediately. Every clause conveys a constraint the agent could act on.

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

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

With no output schema, the description correctly takes on the return contract — grid rows, per-cell first grid column, gridSpan, vmerge states, and paragraph addresses — plus the numbering semantics needed to interpret `table` and `at`. 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 description coverage is 100%, and the schema's own descriptions largely duplicate the description's story-numbering explanation for `at` and `table`. The description adds the returned-grid shape but no new syntax, formats, or edge-case meaning for the three parameters, so the baseline 3 is appropriate.

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

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

The description names the exact resource and its contents ('One table's grid: its rows of cells') and enumerates the per-cell fields (col, span, vmerge, paragraph addresses), so an agent can immediately tell this is a read of a table structure rather than of paragraphs (para_get) or a row mutation (table_row_delete). Scope limits are stated, including that text-box/DrawingML tables are not counted.

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 useful addressing context ('table numbers the main story only; at works in any story'), which implies how to reach non-main-story tables, but it never states at a tool level when to pick table_get over siblings like para_get or outline, nor any exclusions. Usage is inferable rather than 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?

Annotations only declare readOnlyHint=false, so the description carries most of the burden and does it well: it discloses that the deletion is a tracked change (w:trPr/w:del, tracked deleted runs) rather than an irreversible erase, and that vertically merged rows are rejected. It does not say whether a refusal raises an error or is a silent no-op, nor anything about author/tag interaction.

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

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

Two tight sentences with the operation and its tracked-change semantics front-loaded, followed by the refusal precondition. No filler or restatement of the name.

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 with no output schema, the description covers the critical unknowns: mutation style (tracked change) and the blocking precondition. It omits error-vs-noop behavior on refusal and dry_run/expect interaction, which leaves a small gap but not a crippling one.

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 86%, so the schema already documents doc, row, table, author, tag, expect and dry_run. The description adds no parameter-level meaning beyond the row/table semantics already implied, so the baseline of 3 is appropriate.

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

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

States a specific verb (delete) and resource (a row of a body table), and its counterpart sibling table_row_insert makes the pairing unambiguous. The scope qualifier 'body table' also matches the numbering convention of table_get, so the agent knows exactly which object is targeted.

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 a when-not condition: the call is refused for a row containing a w:vMerge cell, which is a genuine precondition an agent must check before invoking. It does not name an alternative tool (e.g. table_get for row numbering) or describe the untracked-delete path, 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?

With only readOnlyHint=false available, the description carries extra weight and delivers: it discloses that the insert is recorded as a tracked change ('w:trPr/w:ins, tracked text') and states the vertical-merge refusal rule. It omits mention of dry_run/preview behavior and author/expect semantics, so it is strong but not exhaustive.

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

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

Two dense sentences, zero filler, with the operation, the anchor parameter, and the failure condition all front-loaded. Every clause carries information an agent needs.

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