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

The description is exceptionally transparent about behavior: batch validation before any mutation, batch-start text consistency, stale anchors refusing the entire batch, ordered execution, keep deletes last, auto-backup behavior, atomic save, live editing as one undo step, and rollback on mid-batch failure. These details go far beyond the single readOnlyHint=false annotation which merely signals mutability.

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?

Though long, the description is dense with necessary information and every sentence earns its place. It is front-loaded with the core batch behavior, then covers edit operations, validation semantics, execution order, live-document behavior, and concludes with a direct usage guideline.

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

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

Given the tool's complexity, the description is remarkably complete. It covers all op types, anchor sources, validation semantics, failure handling, live/edit behavior, and the chaining workflow via fresh anchors. Since an output schema exists, the description correctly focuses on behavior and usage rather than return values.

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

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

Schema description coverage is 0%, so the description must carry full parameter meaning, and it does. It thoroughly explains the edits array structure, each op type with its fields, anchor formats, occurrence semantics, and special cases like set_cell anchors. It also clarifies backup=False behavior and the atomic save behavior.

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

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

The description opens with a specific verb and resource: 'Apply a batch of anchor-addressed edits in one call'. It clearly distinguishes this batched tool from standalone single-edit tools by stating 'Use this when a change needs two or more edits; for one, use the standalone 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?

Explicitly states when to use this tool versus the standalone alternative: 'Use this when a change needs two or more edits; for one, use the standalone tool.' It also establishes the required workflow by specifying anchors come from get_document_view and instructs to re-view and resend on stale anchors.

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 readOnlyHint=false annotation, the description discloses important behaviors: auto-backup rotation, backup=False skip, atomic validated save, refusal of documents open in Word, and Heading1-9 auto-creation. This gives the agent critical side-effect information that annotations alone would not convey. No contradiction with annotations 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?

The description is dense and packed with useful distinctions, alternatives, and behaviors, with no filler. It is slightly long, but every sentence adds operational value. The front-loaded purpose and mode split make it easy to parse despite the density.

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 this is a mutation tool with five parameters, zero schema description coverage, and only readOnlyHint=false as annotation context, the description is remarkably complete. It covers the two operation modes, the relevant parameter behavior, error-prone states (Word-open refusal), save safety, and batch workflow routing. The presence of an output schema means return-value details are not required here.

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

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

Schema description coverage is 0%, so the description must compensate, and it does. It defines the range parameter shape ('{start,end} (locations or bare indices)'), the target parameter shape ('{search:{text, occurrence?}}'), and the backup parameter's effect ('backup=False skips rotation'). It even clarifies that style refers to a named style and that defining new named styles belongs to the academic pack.

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

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

The description opens with a specific verb and resource: 'Apply a named style.' It then distinguishes two distinct modes—paragraph style via range and character style via target—so an agent immediately knows what operation is being performed. It also separates itself from set_paragraph_format and apply_edits, making purpose unambiguous.

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

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

It explicitly says when to use an alternative: 'For an outline level without visual change use set_paragraph_format' and 'For batches, use apply_edits.' It also explains when to chose range versus target ('applies a paragraph style' vs. 'applies a character style to the matched text instead'), leaving little 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 description goes well beyond the readOnlyHint=false annotation by detailing the refusal behavior when dest_path exists, the overwrite=True escape hatch, and the .ks4w-backups rotation that makes overwrite undoable via manage_backups restore. This gives an agent accurate expectations about destructive behavior and recovery.

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 dense sentences carry the purpose, safety-critical overwrite behavior, and tool-boundary routing with no filler. Each sentence earns its place, and the core action 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 copy tool, the description covers the operation, the main edge case (existing destination), the undo path, and exclusions like split/merge and multi-document work. Since an output schema exists for return values, omitting output details is acceptable and 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?

Even with 0% schema description coverage, the description adds meaningful semantics for dest_path (explicit path, contrasted with snapshot naming) and overwrite (default refusal, backup rotation, undoability). file_path is not described explicitly, but its role as the source document is reasonably inferable from 'Copy a document' and the required parameter names.

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

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

The description states a specific verb and resource ('Copy a document byte-for-byte') and immediately distinguishes itself from manage_backups action='snapshot' and the assembly pack for split/merge/multi-document work. An agent can clearly tell what this tool does and which siblings it is not.

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 a concrete use case ('to a new DTG-stamped filename before editing') and contrasts with manage_backups snapshot (which names the copy for you) versus this tool's explicit dest_path. It also routes split/merge/multi-document work elsewhere, but it doesn't explicitly phrase a when-to-use/when-not-to-use rule.

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

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

Annotations only mark readOnlyHint false, so the description carries the burden of behavioral disclosure. It adds meaningful context: the tool refuses to overwrite, auto-creates parent directories, and produces a blank document. No contradiction with annotations.

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

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

Every sentence earns its place: purpose, overwrite exception and alternative, parent-directory side effect, downstream workflow, and template alternative. The information is front-loaded and there is 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 2-parameter creation tool, the description covers the key behaviors needed to call it correctly: no overwrite, automatic parent directory creation, and blank output. The output schema exists, so the absence of return-value detail is acceptable.

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

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

With 0% schema description coverage, the description compensates by explaining that file_path is the location of the new .docx file and title is an optional core property. It does not detail every validation rule, but for only two simple parameters the semantic roles are clear.

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: create a new blank .docx file with an optional title core property. It also distinguishes itself from copy_document by explicitly noting that it refuses to overwrite existing files.

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

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

It gives explicit routing guidance: use copy_document with overwrite=True when overwriting is needed, and go to the assembly pack for template-driven builds. It also lays out the intended next steps for populating the document, making it clear when this tool is the starting point.

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 in annotations, the description carries the behavioral burden and does so thoroughly. It discloses the backup rotation behavior, backup=False semantics, atomic validated save, bold header default, and the refusal to operate on documents open in Word.

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

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

The description is dense but ordered: purpose first, then formatting, placement, file-import alternative, save/backup behavior, and failure condition. Every sentence adds new information and no filler is present.

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

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

Given the output schema exists and annotations are minimal, the description supplies the required context: input format, options, insertion behavior, safety/backup behavior, and error condition. An agent can reliably decide whether and how to call create_table from this text alone.

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

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

Schema description coverage is 0%, but the description compensates for most parameters: data as 2D strings, header_row toggle, location object forms/omission semantics, and backup flag behavior. The only parameter left unexplained is width_pt, whose effect on table layout is not described.

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

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

The description opens with a specific verb and resource: 'Create a table from 2D string data' and clarifies the exact formatting (single-line borders, bold repeating header). It also names import_table as the alternative for file-based input, distinguishing this tool from the CSV/JSON import path.

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

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

It explicitly tells the agent when to use this tool (2D string data) versus import_table (CSV/JSON files). It also specifies placement rules, the 'after' positioning constraint, and the Word-open refusal, so the agent knows when the call will fail.

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 is rich in behavioral detail beyond the readOnlyHint=false annotation: it discloses side effects (image/chart media removal, hyperlink unwrapping, bookmark marker removal), refusal conditions (locked controls, Word-open documents, ambiguous hyperlink matches), and persistence behavior (atomic validated save, backup rotation semantics including backup=False). These are exactly the kind of non-obvious effects an agent needs to know.

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 long but densely packed; almost every clause introduces a constraint or behavior that is not available elsewhere. It is front-loaded with the core purpose and type list. A bulleted breakdown of per-type addressing would improve scanability, but there is no redundant or filler content.

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

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

For a complex deletion tool with five parameters and no schema descriptions, the description is unusually complete: it covers all supported types, addressing modes, side effects, refusals, backup behavior, and sibling routing. The presence of an output schema means return-value documentation is not required, and nothing critical appears missing.

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

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

Schema description coverage is 0%, so the description carries the full burden of explaining parameters. It does this well for most: the polymorphic id semantics are detailed per type, type is fully enumerated, location is explained as a search object, and backup behavior is specified. file_path is not explicitly described, but its meaning is conventional and implied by the tool's purpose.

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

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

The description opens with a specific verb and resource: 'Delete one document element that has no lifecycle tool of its own,' immediately scoping the tool. It enumerates the supported types (equation, image, chart, bookmark, hyperlink, caption, reference_list, content_control) and explicitly distinguishes it from sibling tools by listing what it does not delete.

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

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

The description gives clear when-to-use guidance: use it for elements without their own lifecycle tool, and lists specific alternatives for the other cases (notes in manage_note, comments in manage_comment, sources in manage_source, tables in delete_table, paragraphs in delete_paragraphs). It also explains how to address each supported type, so an agent can decide correctly before invoking.

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 indicate readOnlyHint=false, so the description carries the disclosure burden. It richly reveals mutation-related behaviors: refusal to cut fields/section breaks, empty-paragraph fallback, tracked deletion behavior, expect_start/expect_end no-op safeguards, auto-backup rotation semantics, and live serialized editing. No contradiction with annotations.

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

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

Dense but efficient; every sentence adds a distinct behavioral rule or warning. The content is front-loaded with the core operation, and caveats follow logically. A bulleted list could improve scannability, but for the volume of caveats the length is justified.

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

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

For a 10-parameter destructive operation with no destructiveHint annotation, this description covers the critical edge cases: guarded ranges, empty result handling, backup behavior, live-editing semantics, and safe-deletion expectations. The existence of an output schema covers return values. Minor omissions (author semantics, live value options) keep it from a 5.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies start/end inclusive semantics, range objects, track, expect_start/expect_end conditions, backup behavior, and live editing. It does not explain the author parameter or enumerate live value options, but the essential parameters are well interpreted.

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

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

Description opens with a specific verb and resource: 'Delete body paragraphs' and specifies the exact addressing scheme (0-based inclusive index/range). This clearly distinguishes it from sibling tools like delete_table, delete_element, and apply_edits, and mentions apply_edits specifically for batch operations.

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

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

Explicitly redirects batch work to apply_edits ('For batches, use apply_edits') and describes when live editing applies. It does not enumerate conditions for choosing this over delete_element or delete_table, but the domain-specific semantics ('body paragraphs', refusal of field/section break cuts) give strong contextual signals.

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 mark readOnlyHint=false, so the description carries the burden of explaining destructive behavior. It does this thoroughly: nested tables are removed with the host, backup slots rotate in .ks4w-backups, backup=False only skips rotation, the save is atomic and validated, and Word-open documents are refused.

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 main action is front-loaded in the first sentence, and each subsequent sentence adds necessary behavioral or usage detail without repetition. The text is dense but well organized and 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 destructive table tool with an output schema present, the description covers what is deleted, how to identify the target, side effects on nested tables, backup behavior, save semantics, and a failure condition. No critical operational detail 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?

With 0% schema description coverage, the description compensates strongly: table_index is fully specified as 0-based among body-level tables in document order and sourced from list_elements/get_document_view, and backup behavior is defined. file_path is not explicitly described, though its meaning is clear from the tool 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?

The opening sentence states a specific action and object: 'Delete a whole table and its contents.' It also clarifies the meaning of table_index and distinguishes the operation from set_cells, so the agent can identify this as the whole-table deletion tool among siblings like delete_paragraphs and set_cells.

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

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

The description explicitly gives an alternative for a different intent ('To clear cell values while keeping the grid, use set_cells instead') and tells the agent where to obtain a valid table_index via list_elements or get_document_view. It also warns that the tool refuses documents open in Word, which is a clear when-not condition.

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

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

Beyond the readOnlyHint annotation, the description discloses important behavior: it never fails on weird-but-openable documents, every check degrades to a reported problem, healthy=false is reserved for content-breaking issues, and results are stale while Word holds unsaved changes. This gives the agent a realistic model of the tool's failure behavior and freshness guarantees.

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

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

The description is dense but purposeful; the long checklist is justified because it precisely defines the report's contents. It is front-loaded with the core purpose before getting into alternatives and caveats. Minor redundancy exists in saying both 'No live mode BY DESIGN' and 'this reads the saved package's XML,' but no filler sentences are present.

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

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

Given the tool's complexity—one parameter, read-only structural analysis, subtle staleness semantics, and sibling alternatives—the description covers all necessary context: what it checks, when it is stale, how to avoid staleness, and which alternatives to use. An output schema exists, so return-value details do not need to be in the description.

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

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

The schema has one parameter, file_path, with no description (0% schema description coverage). The description partially compensates by explaining that the tool reads 'the saved package's XML' and instructs the agent to 'close the document first', implying file_path must point to a saved, closed document. It doesn't specify supported file extensions, but the single well-named parameter makes this sufficient.

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

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

The description opens with a specific verb and resource: 'Produce a one-call structural health report, read-only', followed by a detailed list of checks. It clearly differentiates itself from siblings by labeling it 'The deep companion to validate(checks=['core'])' and contrasts it with live alternatives like com_validate_opens_clean and get_document_info.

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

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

It explicitly states when to use this tool over alternatives: 'No live mode BY DESIGN: this reads the saved package's XML, stale while Word holds unsaved changes. Close the document first, or use com_validate_opens_clean.../live get_document_info.' It also points to the academic pack for the full validate check battery, giving an agent clear 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?

Beyond the bare readOnlyHint=false annotation, it reveals important runtime behavior: disabled packs free context, the operation is idempotent, the lite core is never disabled, and the result includes disabled packs, tokens removed, and remaining surface. This is exactly the kind of side-effect disclosure an agent needs.

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

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

Three sentences with no filler: the action and session scope are front-loaded, followed by idempotency and result details, and finally the parameter semantics. Every sentence earns its place.

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

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

For a one-parameter, session-scoped mutation with an output schema, the description covers purpose, side effects, valid values, and what to expect in the response. There are no significant missing pieces an agent would need to invoke it correctly.

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

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

With 0% schema coverage, the parameter would otherwise be opaque, but the description explains that 'packs' accepts enable_tools pack names or ['everything'], which is meaningful semantic guidance. It relies on a sibling definition for the full menu, which is acceptable since it points directly to it.

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

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

The description uses a specific verb ('Disable') on a concrete resource ('previously enabled tool packs') and scopes it to the current session, which clearly distinguishes it from enable_tools and other document-focused siblings.

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 context (after packs have been enabled, for this session) and notes that 'packs' uses the same names as enable_tools, giving an agent a clear route to valid inputs. It does not explicitly spell out when not to use it, but the disable-vs-enable polarity is unambiguous.

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

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

The annotation only provides readOnlyHint=false, which is minimal. The description adds substantial behavior disclosure: the operation is idempotent, reports tokens added, can accept the special value 'everything', and token counts per pack indicate a cost/effect. This goes well beyond the structured 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?

The description is long but well-structured: a lead sentence, a compact task map, then bulleted pack definitions. Each bullet conveys unique, necessary information (pack name, token count, feature list), so no sentence is wasted or 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 tool with a single array parameter and an output schema, the description covers all relevant context: valid values, side effects, token costs, the inverse sibling, and task-based pack selection. Since an output schema exists, not detailing return values is acceptable, and there are no obvious missing 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?

The input schema gives 'packs' as an array of strings with 0% description coverage. The description fully compensates by enumerating all valid pack names, offering the special 'everything' option, and mapping tasks to pack names, so an agent knows exactly what strings to pass and what they will enable.

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: 'Enable optional tool packs mid-session' and clarifies that sessions start lite. It also distinguishes itself from the sibling 'disable_tools' by explicitly naming it as the reverse operation, so an agent can tell them apart.

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

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

It explicitly names 'disable_tools' as the tool that reverses this one, giving clear when-not-to-use context. The task-to-pack map provides concrete guidance for selecting the right pack based on the desired capability, and the 'sessions start lite' preface establishes why this tool would be needed at all.

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

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

Despite readOnlyHint already covering safety, the description discloses substantial behavioral detail: the 500-match cap for live plain queries, effective formatting resolution through run, style chain, and defaults, query=None returning every formatted stretch, and labeled text-box matches. These traits are not inferable from annotations or 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?

The description packs a lot into five dense sentences and front-loads the core purpose. It is efficient, though the run-on semicolon structure and repeated 'file-mode only' make it slightly harder to parse 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 an 8-parameter tool with no schema descriptions, the description covers the major modes, limitations, and output shape, and an output schema exists. It is not fully complete because live values, context_chars, and regex behavior for plain queries are not explicitly specified, but the essential calling context 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?

With 0% schema description coverage, the prose has to explain the parameters, and it does for formatting, scope, include_textboxes, query, and live mode. However, context_chars is left to inference, and the regex parameter's exact applicability is only implied by the phrase 'file-mode, no regex.'

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

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

The opening clause states a specific action and resource: 'Find text in paragraphs and table cells; returns locations plus context.' This clearly distinguishes the tool from siblings such as get_text, and the final sentence reinforces that distinction by routing known-range reads to get_text.

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

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

The description gives explicit mode guidance: text-box and formatting searches are file-mode only, while plain queries can run live on open documents. It also provides an explicit alternative: to read a known range, use get_text. This lets an agent choose correctly without inspecting sibling schemas.

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

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

The description discloses important side effects and behaviors: auto-backup behavior, atomic validated saves, live application to open documents, and file-mode-only casing. Since the only annotation is readOnlyHint=false, these extra details carry the behavioral transparency burden well, though it stops short of describing failure modes or permissions.

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

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

The description is compact and information-dense, with no redundant wording. Every sentence adds useful guidance about targeting, constraints, side effects, or sibling-tool distinction.

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 main invocation scenarios and important save/live behaviors, but it is incomplete for a tool with eight parameters and no schema-level descriptions. Missing occurrence semantics and exact accepted values for formatting/case leave gaps, though the presence of an output schema reduces the need to describe return values.

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

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

With 0% schema description coverage, the description must compensate for parameter meaning. It explains formatting, case, range, find, backup, and live mode, but it leaves occurrence completely unexplained and does not specify exact formatting keys or case value formats. The required file_path is also only implied, not described.

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 action ('Apply character formatting or change case') and a specific resource ('on a text range'), making the tool's purpose immediately clear. It also distinguishes itself from the sibling batch tool by noting 'For batches, use apply_edits.'

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 direct usage constraints: target can be range, find, or both; only one of formatting or case per call; and it explicitly redirects batch needs to apply_edits. It could say more about when to prefer format_text over other sibling formatting tools, but the core selection guidance is present.

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

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

Beyond the readOnlyHint annotation, the description explicitly says 'Read-only' and discloses a behavioral conditional: documents open in Word are read live, with same key names, live adds Word's 'words' counter and track_revisions, and omits the part list. This is exactly the kind of non-obvious behavior an agent needs.

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

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

Two sentences, front-loaded with the main purpose and a compact itemized list of returned counts. The second sentence earns its place by clarifying the live behavior rather than padding.

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

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

The output schema covers return values, so the description does not need to. It covers the two key behaviors (overview contents and live mode) and the read-only guarantee; however, it leaves the 'auto' default's exact decision rule unstated, so an agent may need to infer when live is applied.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains the live parameter's effect (adds 'words', track_revisions, omits part list) but does not specify accepted values beyond the schema's default, and file_path is left to inference. file_path is self-evident from the schema and name, so the partial compensation is enough.

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

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

Opens with the verb 'Read' and a specific resource ('one-call document overview'), then enumerates exact contents: paragraph/table/footnote/comment/revision counts, sections, and package parts. This clearly separates it from siblings like get_text, get_outline, or list_elements.

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 'one-call document overview' implicitly tells an agent this is the summary tool, and the live-behavior note adds context, but it never states when to choose this over get_text/get_outline/list_elements or when not to use it. No explicit alternatives or exclusions are provided.

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

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

Despite readOnlyHint=false in annotations, the description fully explains the sole mutation path: "Stamping is the ONE mutation this tool can make and runs only when explicitly requested." It also discloses volatile anchors, the Word open-document behavior, and that plain reads never modify the file, providing far more transparency than 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 description is dense but every clause earns its place: it defines the output format, parameter values, mutation caveats, and sibling routing with no filler. It is front-loaded with the core purpose and structured so that usage, alternatives, and edge-case behavior follow logically.

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

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

For a tool with five parameters, no schema descriptions, and nuanced behaviors, the description covers everything: anchor stability, scope syntax, detail modes, include options, the stamp_anchors side effect, and open-document behavior. The presence of an output schema reduces the need to explain return values, so nothing necessary for correct invocation is missing.

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

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

With 0% schema description coverage, the description carries the entire burden, and it fully delivers: scope is defined with outline and paragraph ranges, detail is expanded with structure/text/full values, include is illustrated with tables and notes, and stamp_anchors is explained. This goes well beyond the schema's bare keys.

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 sentence states a specific action and resource: "Read the document as an anchored markdown projection," and immediately positions it as "the low-token alternative to get_text," differentiating it from a clear sibling. It further specifies the output format (paragraphs, headings, tables, anchors), so the purpose is unmistakable.

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

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

The description explicitly names when to use this tool versus alternatives: it is for orientation and bulk editing, and it closes with "To locate a string, use find_text; to enumerate collections, use list_elements." It also explains when stamp_anchors should be used, giving clear decision 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?

Beyond the readOnlyHint annotation, the description discloses several behavioral details: it detects both style-based and w:outlineLvl overrides, explains the detect_formatted heuristic, and explicitly states the empty-result behavior ('returns a note plus flat structure counts, not an empty list'). It also notes that open documents are read live. These details meaningfully extend what the annotation alone provides.

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

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

The description is compact and front-loaded with the core purpose; the first sentence gives the essential function. A few phrases are cryptic, notably 'detected_via names which' and 'academic pack,' which slightly reduce clarity, but the overall length is appropriate and no redundant filler is present.

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

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

Given the output schema exists and readOnlyHint is present, the description covers detection variants, fallback behavior, and how indices are consumed. The main gap is the 'live' parameter's semantics, which remains ambiguous. Still, the description is sufficient for an agent to call the tool correctly in most cases.

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

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

Schema property descriptions are at 0% coverage, so the description must carry parameter meaning. It clearly explains detect_formatted ('adds a heuristic scan for direct-formatted headings') and makes file_path's role obvious, but it does not explain the 'live' parameter or its possible values beyond the statement 'Open documents are read live.' This leaves one parameter underspecified.

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

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

The description opens with a specific verb-resource pair: 'List every heading with its paragraph index and level.' It further clarifies what is detected (Heading styles and w:outlineLvl overrides) and names the mechanism ('detected_via'), making the tool's purpose distinct from text-fetching or element-listing siblings. The phrase 'TOC generation and heading surgery' additionally frames the intended use without ambiguity.

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

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

The description implies usage for outline-aware operations by mentioning 'TOC generation and heading surgery' and states that indices feed paragraph/outline selectors. However, it does not explicitly say when to choose this tool over alternatives such as get_text, list_elements, or get_document_view, nor does it state any exclusions or fallback conditions.

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

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

Beyond the readOnlyHint annotation, the description discloses critical behavioral traits: it opens no document, starts no Word, contains no path/document/user name, and is safe to paste into a bug report. This goes well beyond the annotation and gives an agent confidence about side-effect-free execution.

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

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

The description is dense but every clause adds information, starting with the core purpose and then detailing return contents and safety properties. It is slightly long, but the length is justified given the breadth of environment information reported.

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 introspection tool, the description fully covers what the tool reports, its operational constraints, and its intended use. Since an output schema exists, return-values need no further description.

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 are zero parameters and the schema coverage is 100%, so the description carries no parameter burden. The baseline of 4 applies because no parameter explanation is needed at all.

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 clear, specific verb ('Report') and resource ('this server's build and environment'), and enumerates exactly what is included: version, tool surface, packs, startup decision, Word tier, sandboxing, OS/Python, update-check. This unambiguously distinguishes it from the document-centric sibling tools such as get_document_info and diagnose_document.

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

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

The description gives clear context for when this tool is appropriate: it needs no document, opens no file, and is paste-safe for bug reports. It does not explicitly name alternative tools or exclusions, but the unique server-info scope makes the intended use easy to infer.

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 beyond the readOnlyHint annotation by adding the important 'reads the last-saved state' caveat and explaining how the output shape varies when merges are present. Error behavior is not covered, but the read-only safety profile is already annotated.

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?

Five dense sentences with no filler; the core purpose is front-loaded and every sentence adds either parameter semantics, output behavior, or routing guidance.

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 table-reading tool, it covers purpose, parameter semantics, nested-table handling, output variants, sibling routing, and state semantics. With an output schema present and readOnlyHint annotated, little essential information 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?

Despite 0% schema coverage, the description explains table_index's 0-based body-level indexing and nested's {row, cell, index} shape including default behavior. file_path is left implicit, but it is self-explanatory.

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

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

States a specific verb and resource: 'Read one table in full', and enumerates exactly what is returned (cell text, merge map, column widths). This clearly separates it from sibling read tools like get_text or get_outline.

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

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

Provides strong context: body-level table indexing and nested-table addressing explain when this tool applies. It also explicitly routes write and reshape operations to set_cells and modify_table_structure, though it does not contrast with other read 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 already provide readOnlyHint=true, and the description reiterates 'Read-only' without contradicting it. It adds substantial behavioral detail: 0-based end-exclusive slicing, filter behavior, include_textboxes preserving body indices, textbox-only mode returning labeled box content with box_index, and live/open-document behavior.

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

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

The description is front-loaded with the core purpose and dense with relevant behavioral rules; no filler. The telegraphic style, especially the textbox/media-forms clause, is terse to the point of awkwardness but still packs the necessary 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 an output schema present and a read-only annotation, the remaining burden is call behavior, which the description mostly covers: slicing, filtering, textbox modes, file-mode restriction, live documents, and sibling routing. Small omissions like exact contains matching semantics and the acceptable values for live keep it from being fully complete.

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

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

Input schema has 0% description coverage, so this description is the only source of parameter meaning. It explains start/end semantics, contains, include_textboxes, and textbox; file_path is self-evident. The 'live' parameter is only indirectly touched by 'Open documents read live, same shape,' leaving a small gap, but the main parameters are meaningfully annotated.

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

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

Description states a clear verb+object: 'Read body paragraphs as [{index, text, style, ...}] with effective styles.' It further scopes by start/end/contains and textbox modes, and distinguishes itself from list_elements for equations and get_document_view for orientation, so it is not confused with siblings.

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 names two explicit alternatives: equations should be read via list_elements type='equations' and orientation via get_document_view. It also specifies when textbox mode is relevant ('file-mode only') and that open documents are read live. This is enough for an agent to decide when to call this tool rather than a sibling.

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

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

The description goes well beyond the readOnlyHint annotation by stating 'Pure guidance: reads nothing, changes nothing.' It also reveals how the tool behaves for each invocation style and that each step includes a one-line rationale.

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

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

The description is compact, front-loaded with the core purpose, and uses each sentence for a distinct role: what it provides, how to invoke it, and its safety profile. The list of task names is long but earns its place by compensating for the missing schema enum.

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 guidance tool with one optional parameter, the description is complete: it covers invocation variants, valid tasks, behavior, and side-effect safety. The presence of an output schema means return-value details do not need to be described.

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

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

The schema has no description for the task parameter, but the description fully compensates by documenting both valid values and the behavior when omitted. It effectively provides an enum-like list of valid task names in prose.

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 this as a guidance tool that returns recommended tool sequences, not a document operation. It distinguishes itself from sibling tools like get_text or apply_edits by explicitly saying it is 'Pure guidance: reads nothing, changes nothing.'

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 explicit call patterns: call with no task to list available tasks, or call with task='<name>' for details. It does not name alternative tools, but no sibling tool overlaps with this guidance function, so the usage context is clear.

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

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

readOnlyHint=false already flags mutation, but the description adds valuable non-obvious behaviors: auto-backup into prev/anchor slots, backup=False skipping rotation only, atomic validated save, and refusal to operate on documents open in Word. These side effects and constraints go 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?

The description is dense but purposeful; it front-loads the core action and then packs relevant details into compact clauses. The heavy use of semicolons and technical shorthand reduces readability slightly, but every sentence contributes useful information.

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

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

Given an output schema exists, the description need not explain return values. It covers break types, placement, backup semantics, save behavior, and an error condition. The main gap is the precise structure expected for the location object, which remains vague despite being a parameter.

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

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

Schema description coverage is 0%, so the description carries the parameter-documentation burden. It explains type values, backup behavior, and location's role/default. However, the exact shape of the location object is not specified, and file_path is only implied by its name, keeping it from a perfect score.

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

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

The description opens with a clear verb and resource: 'Insert a break after the located paragraph.' It then enumerates all supported break types (page, section_next, section_continuous, section_even, section_odd), making the tool's purpose specific and distinguishable from paragraph/formatting siblings like insert_paragraphs or format_text.

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

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

The description gives concrete placement guidance: location picks the paragraph, omit for document end, and section types have distinct semantics. It references set_section_properties as a related tool for section settings. It does not explicitly contrast with insert_paragraphs or state when not to use this tool, so it falls just short of full guidance.

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

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

Beyond the single readOnlyHint=false annotation, the description richly discloses important behaviors: a call creates its own list and resets numbering, continue_from carries on existing numbering, auto-backup to .ks4w-backups occurs, saves are atomic and validated, and documents open in Word are refused. This substantially exceeds what annotations alone provide.

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

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

The description is dense but every sentence adds needed information for an 8-parameter tool with complex nested options. It front-loads the core action first, then systematically documents items, kind, numbering controls, levels, location, and safety behavior. The compact inline syntax for data structures is efficient and avoids redundancy.

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

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

Given the tool's complexity, the sparse schema, and the presence of an output schema, the description covers everything an agent needs: what the tool does, parameter shapes, list formatting options, insertion point behavior, numbering continuation/restart semantics, backup behavior, and a critical environmental constraint. No significant gap remains.

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

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

Schema description coverage is 0%, so the description carries the full parameter-documentation burden. It explains items formats and nesting depth, kind values, continue_from and start_at semantics, the full levels structure with format enums and label syntax, and location meaning. Only file_path and backup are left to self-evidence, and backup is partially covered by the auto-backup behavior statement.

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

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

The description opens with a specific action and resource: 'Insert a bulleted or numbered list', which clearly distinguishes it from siblings like insert_paragraphs, create_table, or insert_break. It also adds the meaningful qualifier 'with real bullet/number glyphs (numbering.xml as needed)', making the tool's purpose precise and concrete.

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

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

The description gives strong operational context—how numbering behaves, when to use continue_from versus start_at, where location points, and that it refuses Word-locked documents. However, it does not explicitly say when to use insert_list versus alternatives like insert_paragraphs or apply_style; that differentiation is implied 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?

Even though annotations only say readOnlyHint=false, the description discloses substantial behavior: insertion with heading handling, format cloning minus outline level, track changes by author, auto-backup, atomic validated save, serialized live editing, and refusal of stale targets. This goes well beyond the minimal annotation signal and accurately reflects a mutating tool.

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

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

The description is dense but every clause adds operational value. It front-loads the core insertion semantics and then covers modes, safety, live-editing behavior, troubleshooting, and batch routing without wasted words.

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

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

For a 9-parameter tool with no schema descriptions, the description provides substantial operational grounding, and the output schema can cover return-value details. Minor gaps remain: the location object shape is not specified, copy_format_from's integer target is ambiguous, and the live parameter values are not enumerated. Still, the description is largely complete for successful invocation.

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

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

Schema description coverage is 0%, so the description carries the burden, and it covers most parameters well: paragraphs item fields, heading_level semantics, location default, inherit_format/copy_format_from, track, author, and backup. However, copy_format_from's expected integer meaning is not fully explained, and the exact accepted values for the live parameter are only implied.

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

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

The description names a specific operation and resource: inserting paragraph items, and goes beyond the tool name by specifying the item shape ({text, style?, formatting?, heading_level?}) and the location semantics. It also distinguishes itself from apply_edits by noting that batches should use that sibling.

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

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

It explicitly states when to prefer an alternative: 'For batches, use apply_edits.' It also provides mode-specific guidance, such as file mode limitations for format cloning, live editing behavior for open documents, and how to recover from a stale text-selector target. This gives an agent concrete selection and troubleshooting context.

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

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

Even with readOnlyHint=true already provided, the description adds substantial behavior: it declares read-only file mode, warns to close Word documents first, specifies the {type, count, items} return shape, explains that returned handles feed mutating tools, and documents per-type nuances such as cached results and loud rejection of inapplicable filters. This exceeds what annotations alone convey.

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

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

The description is long but structured and information-dense: core purpose, return contract, then per-type highlights, then filters and preconditions. It earns its length because no enum or parameter descriptions exist in the schema, though a slightly tighter organization would improve scannability.

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

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

For a high-variety enumeration tool with an output schema and readOnly annotation, the description is complete: it covers input selection, return semantics, downstream tool usage, refresh behavior for cached TOC fields, filter behavior, prerequisites, and routing to sibling tools. No critical calling information is left to inference.

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

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

With 0% schema description coverage, the description fully compensates: it lists all legal type values, defines the filter shape as {range: {start, end}, name: substring}, notes that filters apply only where meaningful and otherwise fail loudly, and implies file_path through the file-mode context. This gives an agent enough to construct correct invocations without schema descriptions.

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

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

The description opens with a specific verb–resource pair ('Enumerate any collection') and immediately enumerates the 19 supported element types, making scope precise. It also differentiates from close siblings by stating that the returned ids/indices are the handles consumed by set_/delete_/manage_ tools and by pointing string search to find_text.

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

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

It gives actionable usage context: list then act, use enable_tools to discover element packs, and use find_text when locating a string rather than enumerating collections. It does not explicitly enumerate exclusions versus get_text/get_outline, but the type list and 'enumerate any collection' make the intended use clear enough.

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

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

The description discloses substantial behavioral details beyond the readOnlyHint false annotation: restore rotates current content into prev so a restore is undoable, documents open in Word are refused, validation precedes atomic replace, purge only deletes when dry_run=False, snapshots are never auto-pruned and are untouched by purge scopes, and collisions get numeric suffixes. These traits are essential for safe invocation.

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 long but densely information-packed, with each sentence serving a distinct purpose. It is front-loaded with the core resource and then organized by action, making it easy to scan. Every sentence earns its place, including caveats about undoability, Word-locked files, and snapshot permanence.

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 multi-action tool with eight parameters and no schema-level descriptions, the description is remarkably complete. It covers all actions, all relevant parameter semantics, safety defaults, destructive behavior, naming rules, and operational edge cases. Since an output schema exists, the description does not need to detail return values, and it still notes that exact paths and sizes are reported.

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

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

Schema description coverage is 0%, so the description must carry all parameter meaning, and it does. Every parameter is effectively explained: action values, source options ('prev', 'anchor', legacy .bak-*), scope options ('legacy', 'orphans', 'slots'), dry_run default behavior, dest_dir optionality, label as short suffix, and file_path vs directory usage. It goes beyond the schema by explaining naming conventions and collision handling.

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

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

The description clearly states the tool's purpose: managing automatic backups under a hidden .ks4w-backups/ folder. It enumerates four specific actions (list, restore, purge, snapshot) and identifies the exact resource and behavior for each, making it readily distinguishable from sibling tools that operate on document content rather than backups.

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?

Each action is given an explicit use case: list for inspecting slots and orphans, restore for overwriting a file from a backup, purge for deleting backups with scoped options, and snapshot for creating permanent copies. The description also states critical operational defaults such as dry_run defaulting to TRUE, and it clarifies when file_path vs directory should be used.

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?

This is exceptionally transparent about side effects: preview dry-runs without touching the file, max_replacements aborts with no changes, live edits appear as one Ctrl+Z step and remain unsaved, file mode creates auto-backups and does an atomic validated save, and tracked replaces never re-match their own markup. These disclosures go far beyond the minimal readOnlyHint=false annotation and accurately describe mutation behavior.

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

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

The description is information-dense but poorly structured: multiple distinct concerns (safety, preview, formatting, live editing, backup, siblings) are packed into one run-on wall of text with semicolons. It is front-loaded with purpose, and every sentence carries useful content, but the lack of grouping or paragraph breaks makes it harder for an agent to parse and retain, so it is not a model of conciseness.

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 mutation tool with 10 parameters, the description covers the core operation, scope, preview output fields, formatting restrictions, safety limits, tracking behavior, live-edit semantics, backup handling, and sibling routing. The output schema exists, and the description still adds useful detail about result fields like live:true and skip counters, so nothing critical appears missing.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it delivers. It explains the replacements item shape {find, replace, regex?}, enumerates scope values, defines preview=true, max_replacements, track, author, backup, live, and find_formatting semantics. No parameter is left to pure guessing.

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 line, 'Batch find/replace, safe across Word's fragmented runs,' names a specific verb and resource while immediately flagging the tool's distinguishing value. It also differentiates from siblings by explicitly pointing to set_paragraph_text and apply_edits for cases where this tool is not the right fit.

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 concrete when-to-use guidance: use set_paragraph_text when a find string would be unwieldy, and use apply_edits for anchor-scoped edits. It also prescribes a full preview-then-rerun workflow with max_replacements, making the correct invocation sequence explicit.

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

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

Beyond the single readOnlyHint=false annotation, the description discloses substantial behavior: tracked changes by author, live mode restrictions, merge awareness, auto-backup behavior, atomic validated save, and serialization behavior in Word. This gives the agent a strong sense of side effects and constraints without needing to infer them.

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

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

The description is dense but every sentence adds useful information. It could benefit from bullets or segmentation for readability, yet it remains appropriately sized and opens with the primary purpose. The mode distinctions and caveats are packed in without fluff.

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

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

Given the tool's complexity (9 parameters, multiple modes, backup behavior) and the presence of an output schema, the description covers most critical decision points. It explains mode restrictions, backup behavior, and alternative tool routing. Minor gaps remain around the live parameter semantics and author usage, but they are not critical.

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

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

With 0% schema description coverage, the description does heavy lifting by explaining the edits, block, and nested parameter shapes with concrete examples. It also clarifies backup=False semantics. Some parameters like author and live are only implicitly covered, but the core complex parameters are well described.

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

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

The description opens with a specific verb and resource: 'Write many table cells in one call,' which clearly defines the tool's scope. It further distinguishes itself by enumerating modes (edits, block, nested) that map to specific table-write scenarios. This effectively separates it from sibling tools like apply_edits.

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 explicit routing guidance with 'For batches, use apply_edits,' naming the sibling alternative. It also provides mode-specific usage context, such as live mode refusing vertical merges and file mode being merge-aware. However, it does not fully enumerate when not to use set_cells beyond the batch reference.

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

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

The description goes well beyond the minimal readOnlyHint=false annotation by disclosing auto-backup, atomic validated saves, serialized live editing, refusal of shading/borders/tab_stops on live documents, and the non-visual nature of outline_level. These are important behavioral traits that cannot be inferred from the schema or 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 description is dense and front-loaded with the core action and selection contract, followed by formatting keys and behavioral caveats. Each clause adds useful information, though the final apply_edits sentence is slightly confusing and could be reworded for clarity.

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

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

The description covers selection semantics, formatting keys, live-editing constraints, backup behavior, and an alternative tool, which is sufficient for a safe first call. The presence of an output schema reduces the need to describe return values, but the live/backup parameter choices and the exact relationship to apply_edits remain somewhat underspecified.

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

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

With 0% schema description coverage, the description compensates well by defining the two exclusive selection forms, listing all formatting keys, and specifying outline_level's 0-8 range and null-removes behavior. It does not fully explain the live and backup parameter options, but the core invocation semantics are clearly established.

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 action—setting paragraph formatting—and the target selection mechanism (indices or start/end range), and enumerates the supported formatting keys. However, the closing instruction 'For batches, use apply_edits' introduces ambiguity about whether this tool or its sibling is the correct choice for batch operations.

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

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

The description offers some routing guidance by naming apply_edits as a batch-oriented alternative and by describing live-editing restrictions. It does not explain when to prefer this tool over format_text or apply_style, and the word 'batch' is used inconsistently—first as this tool's scope, then as a reason to use apply_edits.

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 readOnlyHint=false annotation, the description discloses index-shifting risk, the refusal-on-mismatch behavior of expect, auto-backup behavior, atomic validated saving, live-edit/serialization semantics, and refusal for tracked-revision paragraphs. It aligns with the annotation (write operation) and adds substantial behavioral context.

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

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

The description is dense but every sentence earns its place: purpose, addressing, safety, backup, live behavior, and batch routing. No filler or repetition of schema fields.

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 concise mutation tool it covers risk, failure modes, backup, transaction safety, live-document implications, and the batch alternative; it also references the returned replaced_text for verification. This is a complete operational picture, especially with an output schema available.

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?

Although schema description coverage is 0%, the description compensates by explaining the location object variants, expect as a required substring guard, backup behavior, and live-edit semantics. new_text and file_path are self-evident, so the most ambiguous parameters are meaningfully documented.

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

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

The description opens with a specific verb and resource: 'Replace one paragraph's full text,' and adds the preserving condition 'keeping style and base formatting.' This clearly differentiates it from sibling formatting tools like set_paragraph_format and batch tools like apply_edits.

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 direct usage instructions for locating the target ('address it with a location object'), explains the safety condition for using expect, and explicitly routes batch work to apply_edits. This tells an agent exactly when and how to use the tool versus alternatives.

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