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

The description goes far beyond the `destructiveHint` annotation by disclosing batch validation before any mutation, all-or-nothing stale-anchor behavior, ordered execution, backup rotation control, atomic save, and live Word editing as one undo step with rollback. This is highly valuable behavioral context the annotations do not provide.

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

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

Every sentence carries necessary operational information, and the content is front-loaded with purpose and anchor source. It is dense and somewhat long, but that is justified by the number of op types and behavioral caveats. The structure could be improved with more visual separation, but 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?

Given a 5-parameter schema with 0% description coverage and no nested schema details, the description covers anchors, op shapes, batch semantics, failure modes, ordering, backup behavior, live mode, and the com-live retry path. With an output schema present, the return contract does not need to be spelled out further.

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 is the only real documentation for the parameters. It fully documents each op type and its fields, explains `backup=False`, clarifies atomic validated save, and describes live behavior. Without this, constructing valid `edits` entries would be impossible.

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

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

States a specific action: 'Apply a batch of anchor-addressed edits in one call'. It names the anchor source (`get_document_view`) and explicitly differentiates from single-edit usage by saying to use the standalone tool for one edit. This clearly distinguishes it from sibling tools.

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

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

Explicitly says to use this tool when a change needs two or more edits, and to use the standalone tool for a single edit. It also gives operational guidance for stale anchors, re-view/resend, and the `com_save_document` prerequisite in com-live mode. No inference is required.

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 mark the tool as destructive (destructiveHint=true). The description adds valuable context beyond that: auto-backup with a skip switch, atomic validated save, and refusal of documents open in Word. This contextualizes the destructive nature and the safety mechanism, though it does not mention error behaviors for missing styles or invalid ranges.

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: it states the core action first, then differentiates modes, then gives alternatives and safety notes. Every sentence adds information; none is filler. It is slightly dense but not bloated.

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

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

An output schema exists, so return details need not be explained. The description covers both invocation modes, sibling routes, backup behavior, file locking, and atomicity. The only notable gap is the precedence rule when both range and target are supplied, but the conditionals imply mutual exclusivity, making this a minor omission.

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 the semantic burden. It does explain range={start,end} with locations/bare indices, target={search:{text, occurrence?}}, and backup=False skips rotation. file_path and style are not elaborated, but style is effectively 'named style' and file_path is self-evident, so the core parameter meanings are conveyed.

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') and immediately distinguishes paragraph-style application via range from character-style application via target. It also names siblings (set_paragraph_format, apply_edits) to differentiate boundaries, so an agent can tell this tool apart without inspecting other schemas.

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

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

The description gives explicit when-to-use guidance: use set_paragraph_format for outline levels without visual change, use apply_edits for batches, and use range vs target for paragraph vs character styles. This is direct, actionable routing with no ambiguity left to inference.

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

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

Goes well beyond the annotations by disclosing the refusal behavior on existing dest_path, the overwrite gate, and the backup rotation into .ks4w-backups for undoability. These are non-obvious side effects an agent must know before calling the 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?

Every sentence delivers a distinct piece of information: core operation, typical use, alternative, overwrite behavior, backup consequence, and domain boundaries. The description is compact despite covering a surprising amount of nuanced behavior.

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

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

With 3 simple parameters and an output schema, the description covers the key behavioral risks: destination collision, overwrite, and recoverability. It also routes to relevant siblings. Nothing critical 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?

Schema coverage is 0%, but the description explains dest_path's explicitness, overwrite semantics, and the backup behavior of overwritten destinations. It doesn't explicitly describe file_path, but that parameter is self-evident from the tool's name and description.

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 operation on a specific resource: 'Copy a document byte-for-byte'. It differentiates itself from manage_backups and assembly-pack tools by giving concrete examples and naming the sibling alternatives.

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

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

Explicitly frames the tool for pre-edit backup ('before editing') and contrasts it with manage_backups action='snapshot', which auto-names copies. It also points out that split/merge and multi-document work live elsewhere, giving an agent clear selection criteria.

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 annotations, the description discloses important behaviors: it refuses to overwrite existing files, auto-creates parent directories, and optionally sets the title core property. This adds meaningful side-effect information, though it does not describe error handling or permissions, which would have pushed it higher.

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 four tight sentences with the main action front-loaded, followed by a key safety behavior, an explicit alternative, and workflow context. Every sentence earns its place and there is no redundant restating of the title or schema.

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

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

For a two-parameter creation tool with an output schema and clear annotations, the description covers the essential call behavior, overwrite refusal, directory creation, and follow-up workflow. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 0%, so the description must compensate. It does explain the title parameter as an optional core property, but file_path is only inferred from its name and the tool's purpose; no format, extension, or path-resolution details are provided. This is adequate but leaves a gap.

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

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

The description names a specific verb ('Create'), a concrete resource ('a new blank .docx file'), and the optional title behavior. It also distinguishes itself from copy_document by explicitly stating it refuses overwrites, so an agent can clearly tell this tool apart from its 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?

The description gives explicit routing guidance: use copy_document with overwrite=True when overwriting is intended, use this tool for blank-file creation, and use assembly-pack tools for template-driven builds. It also names follow-up population tools, giving the agent a clear workflow 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?

Goes well beyond the annotations: it discloses auto-backup rotation semantics, atomic validated save, and refusal of Word-open documents. No contradiction exists with readOnlyHint/destructiveHint.

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, all earning their place: core behavior, location semantics, alternative routing, backup behavior, and a safety warning. Front-loaded with the main action.

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

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

With an output schema present, return formatting is covered elsewhere. The description handles safety, location, and backup behavior well; the only notable omission is width_pt, so the definition is nearly complete but not fully.

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 description gives meaning for data, header_row, location, and backup, which compensates for the 0% schema coverage. However, width_pt is entirely undocumented, and file_path is only implicitly understood from context, leaving a minor but real gap.

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

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

The description names a specific verb/resource ('create a table from 2D string data') and distinguishes it from the CSV/JSON path via import_table. It also separates clearly from table-management siblings like delete_table, get_table, 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?

Explicitly routes CSV/JSON imports to import_table, explains location behaviors and the 'after' positional constraint, and states the default append-at-end behavior. This is strong when-to-use and when-not-to-use guidance.

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

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

Beyond the destructiveHint annotation, the description discloses side effects (removal of media, chart, and embedded-workbook parts), backup rotation behavior, atomic validated save, refusal of locked controls and Word-open documents, and the unwrap/drop-relationship behavior for hyperlinks. This substantially 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?

Though dense, the description earns its length: every clause maps to a decision an agent must make. The scope is front-loaded and the content is grouped per element type with consistent delimiter usage.

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 tool with 5 parameters, 0% schema coverage, and many element variants, the description covers addressing, side effects, refusals, backup behavior, and exclusions. Nothing essential is left unspecified.

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 does. It explains how id, location, type, and backup are used differently across element types, including index, read order, name, target URL, tag, and skip-rotation semantics.

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

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

States a specific verb and resource: delete one document element with no lifecycle tool of its own. It enumerates the exact element types covered and explicitly contrasts with sibling tools like delete_table and delete_paragraphs, so an agent can readily distinguish it.

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

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

The description explicitly says when to use this tool versus alternatives: 'Objects with lifecycle tools stay there' and names each sibling tool for notes, comments, sources, tables, and paragraphs. It also gives per-type addressing rules and refusal conditions, providing full usage routing.

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

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

Annotations only state destructiveHint=true and readOnlyHint=false; the description adds substantial behavioral detail beyond that: refusal conditions, the one-empty-paragraph leftover, expect_start/expect_end no-op semantics, backup rotation behavior, and live-edit serialization with unsaved state. This is exactly the kind of context the annotations cannot 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 efficiently front-loaded, opening with the core deletion mechanism before edge cases and guards. Every sentence conveys a distinct behavioral fact. It is slightly telegraphic, but for a 10-parameter destructive tool the compactness 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 destructive 10-parameter tool, the description covers the core semantics, edge cases, and safety behaviors well. An output schema exists, so return-value documentation is not needed. Minor gaps remain around the live parameter's effect and author's role, but nothing that would block correct invocation in the common case.

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 compensates well for most parameters: start/end indexing, range object shape, track semantics, expect_start/expect_end guards, and backup behavior are all explained. However, live and author are never mentioned, leaving two of ten parameters effectively undocumented.

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 ('Delete body paragraphs') with precise indexing semantics (0-based inclusive start/end, range objects). The qualifier 'body paragraphs' and the closing 'For batches, use apply_edits' distinguish it from siblings like delete_table, delete_element, and apply_edits without needing to open their schemas.

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

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

The description explicitly names apply_edits as the alternative for batch operations and gives concrete when-not conditions ('Refuses ranges cutting a field or a section break'). It lacks an explicit comparison to delete_element for single-element deletion, but the context for when this tool applies 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?

Even though destructiveHint=true already signals mutation, the description adds substantial behavioral context: nested tables are removed with the host table, auto-backup behavior is described, saves are atomic and validated, and documents open in Word are refused. There is no contradiction with the annotations.

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

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

Three dense sentences with no filler. The core action is front-loaded, followed by index lookup guidance, the alternative, backup behavior, and a failure condition. 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?

For a destructive tool with annotations and an output schema, the description covers the key parameter semantics, alternative routing, backup behavior, and an important failure mode. Nothing essential 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?

Schema description coverage is 0%, so the description must compensate. It fully explains table_index semantics and gives backup-related behavior, but file_path is only implicit from its name and the backup=False behavior ('skips rotation only') is somewhat terse.

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 precise verb and resource: it deletes a whole table and its contents. It also scopes the target to body-level tables and explains nested-table behavior, making it clearly distinguishable from siblings like set_cells and delete_element.

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 not to use it ('To clear cell values while keeping the grid, use set_cells instead') and states a failure condition ('Refuses documents open in Word'). It also explains how to obtain table_index via list_elements or get_document_view, which is concrete, actionable guidance.

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

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

Annotations already declare readOnlyHint=true, so the description adds context beyond that by detailing the scope of the health report and the degradation behavior ('Never fails on a weird-but-openable document; every check degrades to a reported problem'). It also reveals the stale-data limitation and the design choice to avoid live mode, which is valuable context not conveyed by annotations.

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

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

The description is dense but well-structured: front-loaded with the core purpose, then behavioral guarantees, usage conditions, and alternatives. While lengthy, every sentence adds value. It could be slightly trimmed, but it's not verbose.

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 (numerous checks) and that annotations provide read-only hint, the description is complete. It covers what the tool does, how it behaves on problematic documents, when to use alternatives, and the critical limitation (stale data). The output schema is present, so return format is already defined. Nothing critical is missing for an agent to invoke it correctly.

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

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

Schema coverage is 0%, meaning the description must compensate for the lack of parameter documentation. However, the only parameter is file_path, which is self-explanatory from the schema. The description doesn't explicitly state that file_path is required or what format it should be, but the name alone is sufficient. The description's enumeration of checks indirectly clarifies the expected behavior, but no additional syntax or constraints are given.

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: produce a structural health report for a document. It enumerates specific checks (content-type coverage, dangling relationships, orphan parts, etc.), making it distinct from siblings like get_document_info or validate. The phrase 'one-call structural health report' is a specific verb+resource, and the read-only nature is highlighted.

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

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

The description provides explicit guidance on when to use this tool: as a companion to validate(checks=['core']), and it specifies when NOT to use it (when the document has unsaved changes in Word). It also names alternatives: com_validate_opens_clean and get_document_info, with clear conditions. This is exemplary usage guidance.

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

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

The description adds meaningful behavior beyond the annotations: it is session-scoped, reclaims context, reports the disabled packs, approximate tokens removed, and remaining surface, and notes the lite core always remains. The idempotentHint annotation is echoed in the description, but the extra session and output details provide transparency the annotation alone does not. There is 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?

The description is compact, with two sentences that front-load the core action and effect before parameter guidance. Every clause adds information: session scope, context reclaim, idempotence, result shape, and valid pack values. No filler or redundant restating of the title appears.

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 has a single parameter, an output schema, and annotations covering idempotence and non-destructiveness, the description supplies all necessary behavioral context. It explains the result contents, the special 'everything' option, and the always-on lite core. The only missing detail is the exact pack menu, but the description directs the agent to enable_tools, which is sufficient for a tool with this complexity.

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

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

Schema coverage is 0%, so the description carries the full burden for explaining 'packs'. It does so effectively by saying it accepts the same names as enable_tools or the special value ['everything'], which tells the agent both the format and the allowed conceptual values. It does not enumerate the pack names, but delegating to enable_tools is a reasonable and functional shortcut given the sibling tool exists.

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 and resource: it disables previously enabled tool packs for the current session, reclaiming context. It clearly differentiates this from enable_tools by describing the inverse operation, and the 'lite core always stays on' detail further scopes what the tool does. No ambiguity remains about the tool's primary function.

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 clearly states the context: disabling previously enabled session tool packs. It directly references enable_tools as the source for valid pack names, which gives the agent a path to understand what values to pass. It stops short of explicit when-not-to-use guidance, but the inverse relationship with enable_tools makes the usage intent clear.

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

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

Annotations already declare idempotentHint=true, but the description adds that it reports tokens added and that disable_tools reverses the change. This gives useful state-change and cost context beyond the structured annotations. There is no contradiction between the description and annotations.

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

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

The description is long but front-loads the core behavior, then provides a task map, then a structured pack list. Every section earns its place given the need to document seven different pack options, and the formatting makes scanning easy.

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

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

With an output schema present, the description does not need to explain return values. It covers when to use the tool, valid pack names, what each pack does, token implications, idempotency, and the inverse operation. An agent has enough information to invoke this tool correctly.

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

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

The schema provides no descriptions and no enums for the packs parameter, but the description fully compensates. It defines valid values as the names below or ['everything'], enumerates all seven pack names, and explains what each pack enables. This turns an opaque array-of-strings schema into a usable selection mechanism.

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 first sentence states a specific action and target: enable optional tool packs mid-session. It also distinguishes itself from disable_tools by noting that disable_tools reverses this operation. An agent can immediately tell what this tool does and how it relates to its 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?

The description gives clear when-to-use context: sessions start lite, so this tool is for adding optional packs mid-session. It names the inverse tool, disable_tools, and provides a task-to-pack mapping, enabling the agent to select the correct pack for common jobs.

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

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

Annotations already declare readOnlyHint=true, and the description adds significant behavioral nuance: 500-match cap, effective-formatting resolution through run/style/defaults, query=None returning every formatted stretch, live-vs-file mode behavior, and textbox labeling. This goes well beyond the structured fields and prevents false assumptions.

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 purpose, and every sentence carries useful constraint information. It is slightly over-packed and repeats 'file-mode only' and 'read-only' (already in annotations), but it remains a compact summary rather than bloat.

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, this description covers most operational constraints: modes, regex rules, formatting resolution, result caps, and an alternative tool. The remaining minor gaps are exact context_chars semantics and how to set live mode explicitly, but the output schema supplies return-shape expectations.

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 most parameter meaning. It explains formatting object semantics, query=None, scope values, regex limitations, and include_textboxes behavior. It does not explicitly define context_chars or the accepted values/effect of the live parameter, leaving a small gap.

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

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

The description states a specific verb and resource: find text in paragraphs and table cells, returning locations plus context. It also names the sibling get_text as the alternative for known ranges, which clearly differentiates this tool from a close relative.

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 get_text for a known range, and it explains mode restrictions (file-mode only for textboxes/formatting, no regex in file mode, live behavior for plain queries). It does not mention search_and_replace, but since this tool is read-only, the main alternatives are adequately covered.

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

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

Annotations already declare destructiveHint=true, and the description adds meaningful behavioral context: auto-backup in file mode, backup=False skips rotation, atomic validated save, formatting goes live on serialized documents, case is file-mode only. This goes beyond the annotation and helps an agent understand side effects and safety.

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 well-organized: it front-loads the core action, then lists options, then constraints, then routing. It is a single paragraph with clear semicolon-separated segments. Slightly long, but every sentence carries 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 8 parameters, 0% schema coverage, and an output schema present, the description covers the key decision points: what can be formatted, how to target text, the one-of constraint, backup behavior, and live vs file-mode. It does not explain 'live' or 'occurrence' semantics, but the overall tool behavior is sufficiently clear for an agent to invoke it 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 description coverage is 0%, so the description must compensate. It explains the meaning of 'formatting', 'case', 'range', 'find', 'backup', and the one-of constraint. It does not detail 'live', 'occurrence', or the exact shape of the range/formatting objects, but it provides enough semantic grounding for the main parameters.

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

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

The description states a specific verb ('Apply') and resource ('character formatting or change case on a text range'), and enumerates the formatting options and case modes. It also distinguishes itself from siblings by noting 'For batches, use apply_edits' and by specifying file-mode vs live behavior.

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 says when to use this tool vs alternatives: 'For batches, use apply_edits.' It also clarifies that case is file-mode only, formatting goes live on open documents, and that one of formatting or case is allowed per call. This gives an agent clear routing and constraint 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?

Even though readOnlyHint=true already covers safety, the description adds valuable behavioral detail beyond annotations: live Word documents are read with 'same key names', live mode adds Word's ComputeStatistics 'words' count and track_revisions, and it omits the part list. This meaningfully informs an agent about mode-dependent behavior and output differences.

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

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

The description is compact, front-loaded with the core purpose, and every sentence contributes information. The live-mode parenthetical is dense but directly relevant, and the read-only note reinforces annotations without unnecessary repetition.

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

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

With an output schema present, the tool does not need to enumerate return values. The description covers core behavior, live-mode differences, and safety. The main gap is the unspecified semantics of the 'live' parameter, which prevents full completeness for an agent trying to use non-default 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 compensate for the schema's silence. It mentions live behavior and output differences, but does not define the 'live' parameter's accepted values or clarify how 'auto' works, nor does it explain file_path's expected format. The live mode description is not clearly mapped to the parameter.

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 identifies a specific action ('Read a one-call document overview') and a clear resource (the document), listing concrete content categories: paragraph/table/footnote/comment/revision counts, sections, and package parts. It is distinct from siblings like get_outline or get_document_view in scope, though it does not explicitly name or differentiate from those alternatives.

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

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

The phrase 'one-call document overview' implies when to use this tool, and the live-mode explanation gives contextual nuance. However, there are no explicit when-to-use or when-not-to-use statements, no exclusions, and no mention of alternatives among the many sibling 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 say readOnlyHint=false, and the description reveals the single mutation path: 'Stamping is the ONE mutation this tool can make and runs only when explicitly requested, with the normal backup and validated save; plain reads never modify the file.' It also discloses volatile anchors without paraIds, the effect of stamp_anchors, and that Word-open documents are read from last saved state — substantial behavior beyond structured 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?

Despite being long, the prose is dense and logically ordered: purpose and output format first, then parameter semantics, then behavioral caveats, then sibling routing. Every clause adds signal and does not repeat schema or annotation 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 tool with 5 parameters, one mutating flag, anchor durability concerns, and multiple output details, the description covers all needed operational context: projection layout, anchor IDs, scope forms, detail levels, table addressing, revision/comment output, optional include behaviors, mutation semantics, and fallback alternatives. The existing output schema relieves it from explaining 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?

Input schema has 0% description coverage, so the description carries the full parameter load. It does: scope gives concrete JSON examples and end-exclusive semantics, detail enumerates the three levels with their markers, include gives example values, stamp_anchors is explained with durability implications, and file_path is the obvious required target. Nothing is left unexplained.

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

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

The description opens with a specific verb and object ('Read the document as an anchored markdown projection') and immediately positions it against get_text ('low-token alternative ... for orientation and bulk editing'). It goes on to specify the output shape (blocks, [hex] anchors, headings, tables), so an agent can distinguish it from siblings without opening schemas.

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

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

It names the primary sibling alternative (get_text) with the exact tradeoff ('low-token alternative') and closes with explicit routing: 'To locate a string, use find_text; to enumerate collections, use list_elements.' This gives clear when-to-use context and points away from the tool for other jobs.

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 adds substantial behavioral detail: it explains detection of w:outlineLvl overrides, the heuristic when detect_formatted=True, fallback behavior when nothing is detected ('returns a note plus flat structure counts, not an empty list'), and that open documents are read live. This is rich, non-obvious context that annotations alone do not provide.

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

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

The description is front-loaded with the core listing behavior and packs useful details into compact sentences. The phrase 'TOC generation and heading surgery: academic pack' is cryptic and somewhat unhelpful, but it does not detract much from an otherwise well-structured description.

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

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

Given the output schema exists and the annotations cover read-only safety, the description covers all essential operational context: detection modes, heuristic behavior, fallback output, live read behavior, and how indices relate to selectors. An agent has enough information to invoke the tool correctly and interpret its purpose.

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

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

The schema has 0% description coverage, so the description must compensate. It successfully explains detect_formatted=True and its heuristic scan, which adds real meaning beyond the schema. However, the 'live' parameter with default 'auto' is not explained, and file_path is only implicitly obvious from context, leaving a partial gap.

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

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

The description opens with a specific action and resource: 'List every heading with its paragraph index and level.' It further clarifies what is detected (Heading styles and w:outlineLvl overrides) and how results are structured, making the tool's purpose unmistakable and distinct from sibling tools like get_text or 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?

The description provides clear context for when this tool is meant to be used, mentioning 'TOC generation and heading surgery' and noting that indices feed location selectors. It does not explicitly name alternatives or exclusions, but the stated use case and read-only framing give an agent enough context to select it appropriately.

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

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

Annotations already declare readOnlyHint=true, and the description goes well beyond that by stating that it opens no file, starts no Word, and is paste-safe with no path, document name, or user name. It also discloses exactly what state it reports, including lock status, Word availability, path sandboxing, and update-check state.

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 information-dense: it front-loads the purpose, enumerates the reported details, and closes with a practical reassurance about paste-safety. A few items, like 'opens no file' and 'starts no Word,' repeat the same idea, but the overall structure earns its length.

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

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

For a zero-parameter tool with an output schema, the description is complete: it tells the agent what information is returned, that no document context is needed, that it is read-only, and that the result is safe to share. 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?

There are zero parameters and 100% schema coverage, so the schema fully documents that no input is needed. The description adds useful confirmation by saying it needs no document or file, which clarifies that no implicit context is required either.

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

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

The description names a specific verb ('Report') and a distinct resource ('this server's build and environment'), then enumerates the exact content. It is clearly distinguishable from every sibling, which are all document-oriented operations like get_document_info and delete_table.

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 spells out that the tool needs no document, opens no file, and starts no Word, which tells an agent this is the universal server-level information tool rather than a document-scoped one. It does not explicitly name alternatives, but no sibling provides an equivalent server-info function, and the context makes the intended use obvious.

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 state readOnlyHint=true, and the description adds meaningful behavior: it reads 'the last-saved state of a document open in Word,' and it explains how output shape depends on whether the table has merges. This goes well beyond 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?

Four sentences, each carrying distinct value: scoping, parameter semantics, output behavior, and usage alternatives. There is no filler, and the most important information is front-loaded.

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

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

Given the tool's complexity and the existence of an output schema, the description covers the essential operational details: index addressing, nested tables, merge-dependent return shapes, and read-only behavior. Nothing critical is missing for correct invocation.

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

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

Despite 0% schema description coverage, the description fully explains table_index semantics (0-based, body-level, document order) and the nested parameter structure ({row, cell, index}, default 0). file_path is self-explanatory, so the parameter guidance is effectively complete.

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: 'Read one table in full,' then enumerates exactly what is returned (cell text, merge map, column widths). It also distinguishes itself from writes/reshapes by naming set_cells and modify_table_structure, making it clear this tool is for reading only.

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 says when to use nested addressing, and explicitly routes write and reshape operations to other tools ('Write with set_cells; reshape with modify_table_structure'). This gives the agent clear when-to-use vs. when-not-to-use guidance.

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

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

Beyond the readOnlyHint annotation, the description discloses slice semantics, contains filtering, textbox behavior, file-mode restrictions, and the live document shape. The parenthetical about set_textbox_text is cryptic, which keeps this from a 5.

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

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

The description is compact and front-loaded with the core behavior and return format. It packs a lot into dense sentences and parentheticals, making it slightly harder to parse, but there is no unnecessary 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 7-parameter tool with no schema descriptions, this is fairly complete: output shape, slicing, filtering, textbox modes, file/live behavior, and equation routing are all covered. The live parameter semantics and the meaning of the get_document_view orientation note remain slightly 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 carries the burden of explaining parameters. It explains start/end indexing, contains, include_textboxes, and textbox; however, the live parameter is only vaguely tied to "Open documents read live," and the contains filter lacks matching semantics.

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

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

The description opens with a specific verb and resource: "Read body paragraphs" and immediately gives the output shape. It also differentiates itself from siblings by routing equations to list_elements and orientation to get_document_view.

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 scoping signals: equations should be read via list_elements, textbox features are file-mode only, and open documents read live. It does not exhaustively contrast with all overlapping siblings like find_text or get_outline, but the main alternatives are identified.

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 adds 'Pure guidance: reads nothing, changes nothing', making the safety profile explicit. It also discloses that calling without arguments lists tasks versus returning sequences, which is genuinely useful 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?

Every sentence earns its place: definition, usage modes, task list, and safety note. The task-name list is long but necessary since no enum is provided in the schema. The structure is clear and front-loaded with the tool's core purpose.

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

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

The description is complete for a simple guidance tool: it explains what it returns in both invocation modes, lists all available tasks, and clarifies the read-only nature. With an output schema present, no further return-format details are needed.

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 fully explains the optional 'task' parameter: its default behavior, how to pass a task name, and the complete list of accepted values. This fully compensates for the schema's lack of parameter 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 states a specific verb ('get') and resource ('workflows' / recommended tool sequences) and explains exactly what the tool provides: step-by-step guidance with one-line reasons. It clearly distinguishes itself from the document-manipulation siblings by positioning itself as pure meta-guidance.

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 explains the two invocation modes: call with no task to list available tasks, or call with task='<name>' for a specific sequence. It also names all valid task values, leaving no ambiguity about how to use the tool.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is partially known. The description adds substantial behavioral context beyond that: auto-backup to prev/anchor slots in .ks4w-backups, backup=False only skips rotation, atomic validated save, and refusal to operate on documents open in Word. This is exactly the kind of mutating-tool behavior 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?

Four dense sentences carry distinct, non-overlapping information: the core action, the type enumeration, the location semantics, and the safety/failure behavior. The definition is front-loaded with the verb+resource and contains no filler or repeated concepts.

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 4 parameters, 0% schema coverage, and an output schema present, the description covers all critical aspects: purpose, type semantics, location, backup behavior, atomic validated save, and the Word-lock refusal. The only minor undefined term is 'located paragraph,' but the description handles this by providing a default behavior (document end), making the tool sufficiently complete for correct invocation.

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

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

Schema description coverage is 0%, so the description itself must explain the parameters. It fully describes type (page vs section_* and their formatting implications), location (picks the paragraph, omitted for document end), and backup (backup=False only skips rotation; auto-backup is default). file_path is implied by the required field and the document context. No parameter is left unexplained.

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: 'Insert a break after the located paragraph,' which clearly states the operation. It then enumerates the type variants (page vs section_*) and introduces the location concept, making the tool unmistakably distinct from sibling insert_paragraphs or delete_paragraphs. The name and title align with the described behavior.

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

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

The description provides clear directional context: it explains the effect of each type option, states that location can be omitted to target the document end, and warns that documents open in Word are refused. It does not explicitly name an alternative tool for inserting normal paragraphs, so it lacks an explicit when-not statement, but the usage context is otherwise 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?

Beyond the annotations, the description discloses important behaviors: each call creates its own list and restarts numbering, it auto-creates .ks4w-backups, saves are atomic and validated, and it refuses documents open in Word. This gives the agent what it needs to anticipate side effects and failure conditions.

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

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

Although dense, every sentence earns its place: main action first, then parameter semantics, then behavioral caveats. No filler or repetition; the compact notation packs a lot of 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?

For a tool with 8 parameters and no schema descriptions, the description is nearly complete. It explains all nontrivial parameters and behaviors, and an output schema exists, so return values need not be described. The only small gaps are the exact shape of the location object and whether the backup parameter disables the auto-backup behavior.

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

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

With zero schema description coverage, the description carries the full burden and succeeds. It explains the items shape ('strings or {text, level} dicts'), the kind enum, the levels array format with all per-level fields and allowed format values, and the continue_from/start_at/location semantics. Only file_path and backup rely on name/default inference, which is acceptable.

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 precise verb and resource: 'Insert a bulleted or numbered list with real bullet/number glyphs.' This clearly distinguishes it from sibling insertion tools like insert_paragraphs or create_table, and the supporting detail about numbering.xml reinforces the specific function.

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

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

The description gives clear usage context: it tells the agent when to use the tool (inserting bulleted/numbered lists), how to continue existing numbering via continue_from from list_elements, and how to set start_at and location. It stops short of explicitly naming alternatives or exclusion cases, but the context 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 description adds substantial behavior beyond the sparse annotations: heading level mapping to outline levels, format cloning behavior (minus outline level), track-guard insertion reporting, auto-backup, atomic validated save, live serialized editing, and stale-selector refusal. No contradictions with readOnlyHint=false or destructiveHint=false.

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 highly efficient; every sentence adds a distinct, non-redundant fact. It opens with the primary action and then layers on caveats and limitations. There is no filler, and the structure flows from core operation to edge cases and alternatives.

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 9 parameters and a schema lacking descriptions, the description covers all essential aspects: item structure, location default, heading levels, format inheritance, tracking, backup, save semantics, live document behavior, and batch routing. An output schema exists, so return values are not required; 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?

With 0% schema description coverage, the tool description carries the full burden of parameter explanation. It defines paragraph item shape, clarifies location default, explains heading_level semantics, describes inherit_format/copy_format_from effects, and mentions track/author behavior. This is comprehensive compensation for the schema's silence.

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, 'Insert paragraphs', and specifies the target as a location object with a clear default (document end). It also distinguishes itself from the sibling apply_edits by explicitly naming it for batch use. There is no ambiguity about what operation this tool performs.

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 guidance: use apply_edits for batches, and notes that inherit_format/copy_format_from work only in file mode. It also includes troubleshooting behavior ('stale text-selector target refuses: save in Word, retry') and describes the live editing context. Clear when-to-use and when-not-to-use signals are 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description aligns with them while adding substantial behavior: return shape {type, count, items}, handle semantics for later tools, per-type highlights, filter behavior including loud rejection, cached results, and refresh guidance. No contradiction 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 long but structured and front-loaded with purpose and return shape. Per-type details add real value rather than padding, though a few could be condensed. For a multi-collection tool with 15+ types, 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?

Given the tool's complexity and the absence of schema descriptions, the description covers purpose, accepted types, return value, parameter semantics, prerequisites, error behavior, and related tools. The output schema exists, and the description still clarifies the return envelope. Nothing critical is missing.

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

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

Schema coverage is 0%, so the description carries the burden. It fully enumerates type values and documents the filter object's range and name substring shape. file_path is left implicit, but 'file mode' and the requirement to close Word documents provide enough context for a conventional file-path parameter.

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 precise action ('Enumerate any collection in one call') and identifies the resource with an exhaustive set of element types. It clearly distinguishes itself from sibling tools like find_text and get_table by framing list_elements as the read-only enumeration step before set_/delete_/manage_ actions.

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 context: read-only, file mode, close open documents first, and list-then-act workflow. It explicitly routes string search to find_text and points to enable_tools for element-specific packs, but it does not systematically enumerate when-not-to-use cases for every sibling tool.

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

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

Beyond the destructiveHint annotation, the description discloses that restore rotates current content into prev first, making restores undoable, and that purge deletes only when dry_run=False. It also explains snapshot permanence, collision behavior, atomic replacement, and Word-open refusal, which gives the agent a strong safety model.

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 necessary behavioral or parameter information. It front-loads the location and slot model, then organizes actions in a logical progression, making a complex multi-action tool easy to scan.

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 four distinct actions, 8 parameters, and destructive potential, the description covers the full decision space: what each action does, which parameters apply, safety guards, naming behavior, and what gets reported. The existence of an output schema means return-value details are not needed, and no critical 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?

With 0% schema description coverage, the description carries the full burden and succeeds: it explains action values, source choices, purge scopes, dry_run semantics, dest_dir, label, file_path, and directory. An agent can correctly choose values without opening any external documentation.

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

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

The description names a specific resource (hidden .ks4w-backups/ folders) and a clear set of actions (list, restore, purge, snapshot), so the agent knows exactly what the tool operates on. It is immediately distinguishable from the document-editing sibling tools and from backup operations that might mutate documents directly.

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 a concrete purpose: list reports, restore overwrites, purge deletes, snapshot preserves. It also notes the dry_run default and the refusal of documents open in Word, which helps avoid misuse. It doesn't explicitly name what not to use this tool for, but no sibling tool overlaps with backup management, so the lack of an explicit exclusion is minor.

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 that the tool is destructive and not read-only, but the description discloses much more: preview dry-runs without touching the file, max_replacements aborts changing nothing, live edits appear as a single undo step and remain unsaved, file mode auto-backs up with atomic validated saves, and tracked replacements never re-match their own markup.

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 and dense, but nearly every clause earns its place by describing a distinct behavior, parameter, or safety mechanism. Its single-paragraph semicolon-heavy structure makes it harder to scan than a bulleted list, though this is a minor issue for such a complex tool.

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

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

It covers preview dry-runs, abort-on-drift behavior, tracked changes, formatting-restricted matching, backup/save safety, Word run fragmentation, live-edit serialization, and sibling routing. Since an output schema exists, omitting detailed return-value explanations 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?

Schema description coverage is 0%, so the description must carry the parameter burden. It does well by specifying the replacement item shape ({find, replace, regex?}), enumerating scope values (body | footnotes | headers | all), and explaining preview, max_replacements, find_formatting, track, and backup. The 'live' parameter is described behaviorally rather than by its accepted values, leaving a small gap.

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

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

The description opens with 'Batch find/replace, safe across Word's fragmented runs,' clearly naming the operation and target resource. It further differentiates itself from siblings by pointing to set_paragraph_text for whole-paragraph rewrites and apply_edits for anchor-scoped 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 explicit routing guidance: use set_paragraph_text when a find string would be unwieldy, and use apply_edits for anchor-scoped edits. It also prescribes a concrete safe workflow: run preview, review counts/refusals, then rerun with max_replacements set to the previewed total.

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 mark the operation destructive, idempotent, and read-write; the description adds valuable behavior beyond that: live mode refuses vertical merges, file mode is merge-aware, backup rotation can be skipped, saves are atomic and validated, and tracked changes are attributed by author. The Word-open sentence is terse but contributes real concurrency 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 and efficient, packing mode syntax, nested behavior, tracking, backup, atomic save, and sibling routing into six sentences with no filler. A couple of phrases are telegraphic, but 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?

Given 9 parameters and 0% schema coverage, the description covers the critical decision points: edit structures, nested targeting, merge restrictions, backup control, atomic save, and the apply_edits alternative. Remaining ambiguity around the Word-open sentence and exact output behavior 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?

Schema description coverage is 0%, so the description carries the burden. It gives concrete shapes for edits, block, and nested, and explains track, author, backup, and live. Required params file_path and table_index are not explicitly described, but their roles are inferable from the tool context; still, this prevents a 5.

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

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

States a specific verb and resource: 'Write many table cells in one call.' It also names sibling apply_edits as the batch alternative, distinguishing the tool from nearby 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?

Provides clear selection context by describing modes (scattered vs block vs nested) and live vs file behavior, and explicitly points to apply_edits for batches. It does not compare against every sibling table tool, but the intended use 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 description goes well beyond the annotations by disclosing auto-backup, atomic validated saves, serialized live editing, refusal of shading/borders/tab_stops on live documents, and the unusual outline_level offset behavior. These are meaningful behavioral traits that an agent needs to anticipate side effects, and none of them contradict the annotations.

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

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

The description is dense but each sentence earns its place: selection constraints, formatting keys, outline_level caveat, save behavior, live limitations, and routing. It is longer than a minimal definition, but the complexity of the tool justifies the length.

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

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

Given seven parameters and an output schema, the description covers the main selection modes, supported formatting keys, and key side effects. Gaps remain around the 'live' parameter's exact values, what happens if no selection form is supplied, and how 'backup' is explicitly toggled. Overall, it is adequate but not exhaustive.

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 burden of explaining parametersebb8-semantics. It explains indices, start/end inclusive ranges, the formatting keys, and outline_level semantics. It does not fully document the 'live' parameter's accepted values or precisely tie 'auto-backup' to the backup parameter, so coverage is strong but not complete.

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 names the operation ('set paragraph formatting') and the target resource ('paragraphs'), and it specifies the selection modes (indices list or start/end inclusive range). However, it does not explicitly distinguish this tool from nearby siblings like format_text or apply_style; the only routing cue appears later with 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 provides useful usage context: it shows how to select paragraphs, notes live-document behavior, and says 'For batches, use apply_edits.' It does not fully explain when to prefer this over format_text or apply_style, but it gives enough context to route an agent for a paragraph-formatting operation.

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

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

Beyond the annotations, the description discloses meaningful behavior: indices shift after edits, expect prevents wrong-paragraph edits, auto-backup in file mode, atomic validated save, live serialized edits, and refusal on tracked-revision paragraphs. This is exactly the kind of context that helps an agent anticipate side effects.

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

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

The description is dense but every sentence adds value: operation, addressing, safety mechanism, backup behavior, live-edit implications, and batch alternative. It is front-loaded with the core action and avoids 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?

Given the tool's complexity (nested location objects, multiple parameters, output schema, annotations), the description covers the critical usage and behavioral aspects thoroughly. The batch alternative, safety guardrails, and live-edit constraints make it complete enough for correct invocation.

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

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

With 0% schema description coverage, the description compensates for the most important parameters: location object variants, expect substring, and backup behavior. It does not explain the 'live' parameter values or file_path explicitly, but file_path is self-evident and the live behavior is partially described, so the key semantic gaps are mostly filled.

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 and resource: 'Replace one paragraph's full text, keeping style and base formatting'. It clearly distinguishes itself from formatting-focused siblings and even points to apply_edits for batches, making the tool's scope 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 this tool (replacing one paragraph's full text), when not to (for batches, use apply_edits), and provides important context such as tracked-revision paragraphs refusing live edits. This is strong routing guidance.

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