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

The description goes well beyond the annotations by disclosing validation-before-mutation, stale-anchor refusal, per-op results with fresh anchors, direct application under track changes, auto-backup, atomic save, and live-edit behavior with rollback on mid-batch failure. It also notes file-mode restrictions for markdown lists/tables and move. This is rich behavioral context.

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

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

The description is dense and front-loaded with the primary purpose before diving into operation definitions. There is slight redundancy (e.g., mentioning 'validated save' and later 'atomic validated save', and repeating backup/lock concepts), but given the tool's complexity, each section earns its place.

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

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

For a tool with this many operation variants and behavioral caveats, the description is highly complete. It covers validation semantics, error behavior, ordering, live vs file modes, backup, and what 'changed' contains. Since an output schema exists, the description correctly focuses on behavior and constraints rather than return-value details.

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 only 20% schema description coverage, the description carries nearly the entire parameter burden. It fully specifies each operation object accepted in 'edits', including optional fields such as occurrence, location, allow_cross_section, and the 't:hex:rNcN' anchor format for set_cell. This thoroughly compensates for the sparse schema.

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

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

The description opens with a specific verb and resource: 'Apply a batch of anchor-addressed edits in one call', and then enumerates the full set of operations (replace, set_text, insert, delete, move, set_style, format, set_paragraph_format, set_cell). This clearly distinguishes it from single-purpose sibling edit tools by emphasizing batch, anchor-addressed, and atomic 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 gives clear usage context: anchors come from get_document_view, edits are batched into one call, and ordering guidance is provided ('Ops run in order; keep deletes last'). It does not explicitly name alternatives or say when not to use this tool, but the context is strong enough for an agent to infer the right scenario.

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?

Annotations only carry false hints that this is not read-only and not open-world, so the description shoulders the behavioral burden. It discloses auto-backup rotation slots (prev/anchor in .ks4w-backups), the exact meaning of backup=False (skips rotation only), atomic save behavior, and refusal to operate on Word-open documents.

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 behavior, location semantics, sibling routing, backup behavior, and the Word-open constraint. It is dense yet well-structured and front-loaded with the primary 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 covers the decision-relevant distinctions, location semantics, and safety/backup behavior well for a 6-parameter tool with no schema-level param descriptions. The only notable gap is the unexplained width_pt parameter, but the parameter name and surrounding context make it inferable enough for a competent agent.

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 adds meaningful semantics for data, header_row, location, and backup. However, width_pt is never mentioned, and file_path is left to name inference, so the compensation is excellent but incomplete.

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

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

The description opens with a specific verb and resource: 'Create a table from 2D string data' with explicit formatting defaults. It also distinguishes itself from format_cells, set_table_properties, and import_table by naming what each sibling is for, so an agent can tell it apart without ambiguity.

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

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

It explicitly routes to alternatives: format_cells/set_table_properties for existing tables and import_table for CSV/JSON files. It also states the location rule (only 'after', omit to append) and the Word-open refusal condition, giving clear 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 already mark this as destructive (destructiveHint=true) and not read-only (readOnlyHint=false). The description adds substantial behavioral detail: 'Refuses ranges cutting a field or a section break; deleting every paragraph leaves one empty one behind,' 'track records tracked deletions,' 'expect_start/expect_end delete nothing unless that index still holds the given text,' and 'Auto-backup in file mode.' These go well beyond the annotations and describe edge cases and side effects, making behavior predictable.

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

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

The description is a single dense paragraph but each sentence contributes information. It front-loads the primary usage (start/end/range), then constraints, then special parameters, then live behavior, and finally the batch alternative. It's not overly verbose, though it could be organized with bullet points for clarity. Still, it's efficient and well-structured.

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 tool has an output schema, so return values are documented there. Annotations cover the destructive nature. The description covers many behaviors: deletion modes, constraints, tracking, expected text checks, backup, and live editing. It doesn't explicitly state what happens on success or error, but given the output schema and the density of details, it is fairly complete for an agent to use correctly. Some edge cases like 'deleting every paragraph leaves one empty one behind' are noted, which is helpful.

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 only 10%, so the description must compensate. It does explain key parameters: start/end/range for the deletion range, track for tracking deletions, expect_start/expect_end for conditional deletion, and backup for auto-backup behavior. However, it doesn't describe 'author,' 'live,' or 'file_path' explicitly, though some are implied (e.g., 'Open documents edit live' implies the live parameter). Given the low schema coverage, it adds meaningful semantics for most parameters but leaves a few self-explanatory ones unaddressed.

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 function: 'Delete body paragraphs by 0-based inclusive index (start, end; end defaults to start) or by range={start, end} location objects.' It also differentiates from siblings by noting 'For batches, use apply_edits,' which explicitly names an alternative. The verb 'delete' and resource 'paragraphs' are specific and 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 provides clear usage context: 'Open documents edit live (serialized), unsaved until saved' and 'Auto-backup in file mode (backup=False skips rotation).' It also gives an explicit exclusion: 'For batches, use apply_edits.' However, it doesn't elaborate on when to use delete_element or other deletion tools, so it's not fully comprehensive but adequate.

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?

Beyond the readOnlyHint annotation, the description discloses the 500-match cap, the file-mode-only constraints, the effective-formatting resolution chain, query=None behavior, and the live vs file mode split. This is rich behavioral 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 compact but information-dense: core purpose first, then mode-specific details, then routing. Every clause adds either a constraint, a behavior, or an alternative, with no filler.

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

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

Given the output schema exists, return values do not need elaboration. The description covers the main behavioral branches, file/live modes, formatting resolution, caps, and the relevant sibling tool, making it complete 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?

With only 13% schema description coverage, the description carries most parameter meaning: formatting, include_textboxes, scope, regex constraints, live behavior, and query=None semantics. It does not explicitly explain context_chars, though the phrase 'returns locations plus context' plus the parameter name partially covers it.

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

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

The description states a specific action ('Find text in paragraphs and table cells'), names the returned artifact ('locations plus context'), and distinguishes itself from get_text by pointing to the known-range case. It also mentions formatting and textbox modes, making the tool's scope unmistakable among siblings.

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

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

It explicitly routes to get_text when reading a known range, states that formatting and textbox searches are file-mode only, and clarifies when live documents are searched ('Plain queries search open documents live'). The read-only note and file/live distinctions provide concrete when-to-use guidance.

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

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

Goes well beyond the destructiveHint=true annotation by disclosing auto-backup, atomic save, substring run splitting with preservation of other formatting, whole-paragraph behavior including marks, and the live/file-mode restriction. These are exactly the side-effect and mutation details an agent needs. No contradiction with annotations.

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

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

Dense and front-loaded; every clause adds operational information and there is no filler or repetition. The telegraphic style is justified by the number of constraints the description must convey.

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

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

For a destructive, 8-parameter tool with an output schema, it covers targeting, side effects, and live mode well. The missing piece is occurrence semantics, and the live values auto/force/off are only implied by 'live-capable' rather than spelled out. Still, most essential call decisions are supported.

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 only 13% schema coverage, the description compensates substantially: it enumerates formatting fields, case values, range/find targeting, and backup/live semantics. The main gap is the occurrence parameter, which interacts with find but is not explained.

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

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

States a specific verb and resource: 'Apply character formatting or change case', then enumerates the exact formatting keys and case modes. This clearly distinguishes the tool from sibling paragraph/style tools like set_paragraph_format and apply_style, even though those are not named.

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

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

Provides strong mode-selection constraints: one of formatting or case per call, range vs find targeting, and live vs file-mode capability. However, it never names sibling tools or states when to prefer this over set_paragraph_format, apply_style, or find_text; the agent has to infer the boundary from 'character formatting'.

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 include readOnlyHint=true, and the description reinforces 'Read-only'. It adds valuable context about the 'live' parameter, explaining behavior for documents open in Word (adds 'words' from ComputeStatistics, omits part list). This goes beyond annotations and is consistent, so no contradiction.

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

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

Two sentences with no filler, front-loading the core purpose and then detailing the live behavior. The second sentence is dense but necessary for nuance. Well-structured and efficient.

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, return values are documented separately. The description covers the read-only nature, the live behavior, and what information is returned. For a read-only overview tool, this is complete enough; the only minor gap is explicit guidance on when to choose this over siblings.

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 covers 50% of parameters (only 'live' has a description). The description elaborates on the 'live' behavior, which directly explains the enum values, but does not add anything about 'file_path' (though that is self-explanatory). It partially compensates for the coverage gap but could be more explicit about parameter meanings.

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

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

The description clearly states a specific verb ('Read') and resource ('document overview'), enumerating the exact content (counts, sections, package parts) and distinguishing itself from siblings by positioning as a one-call overview. It is unambiguous and differentiates from other get_ tools like get_document_view or get_text.

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

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

The description implies use for a high-level overview but does not explicitly state when to use it over alternatives or when not to use it. It mentions 'one-call' which hints at efficiency, but there is no explicit comparison to siblings like get_document_view or get_outline, leaving selection partly to inference.

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

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

Annotations 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?

With readOnlyHint=true already in annotations, the description still adds substantial behavioral context: dual detection mechanisms (Heading styles vs w:outlineLvl), the detect_formatted heuristic with INFERRED levels and confidence, the empty-result fallback (note plus flat counts), and how indices feed location selectors. 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 dense but every sentence earns its place — core behavior, detection nuance, edge case, downstream use. The telegraphic caps style (CANDIDATES, INFERRED) adds slight noise but doesn't waste space; it is appropriately sized for a tool with three behavioral modes.

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

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

Given an existing output schema and annotations covering read-only safety, the description covers the remaining context: detection modes, heuristic behavior and confidence, empty-result fallback, and how the output feeds the location object's selectors. Nothing an agent needs to invoke the tool correctly is missing.

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

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

Schema coverage is low (33%), and the description compensates for the most semantically loaded parameter: detect_formatted gains a full explanation of the heuristic scan and its output semantics. file_path is self-evident and live is already described in the schema enum, so the compensation is adequate where it matters.

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

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

Opens with 'List every heading with its paragraph index and level' — a specific verb, resource, and output shape. It further distinguishes itself from siblings like get_text and find_text by detailing detection of Heading styles and w:outlineLvl overrides, so an agent can separate it from get_document_view and get_table 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?

The closing label 'TOC building: academic pack' provides a stated use case, so this is more than no guidance. However, it names no sibling alternatives and gives no when-not-to-use conditions, leaving the agent to infer when get_document_view or get_text would be a better fit.

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 assert readOnly/openWorld behavior; the description goes beyond by disclosing the two output modes selected by has_merges and the nested-table addressing convention. It also explicitly repeats 'Read-only,' reinforcing the annotation.

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

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

Every sentence carries information: purpose, return variants, nested addressing, and sibling routing. It is front-loaded with the core capability and stays structured without redundancy.

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

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

For a read tool with an output schema and readOnly/openWorld annotations, the description supplies the missing contextual semantics: indexing rules, merge-mode behavior, nested-table invocation, and which sibling tools handle writes/shading/structure changes. Nothing needed for correct invocation is left undocumented.

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 param-documentation burden. It explains table_index as 0-based among body-level tables in document order and fully specifies the nested object shape and defaults, which the bare schema does not convey.

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-resource pair ('Read one table in full') and enumerates exactly what is returned (cell text, merge map, column widths), which distinguishes it from sibling read tools like get_text or 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?

It gives concrete conditions: use has_merges for merged-cell data and nested for nested tables, and it routes mutations to sibling tools (set_cells, format_cells, set_table_properties, modify_table_structure). It lacks an explicit contrast with alternative read-only tools, but the table-specific scope is clear enough.

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

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

Beyond the readOnlyHint annotation, the description discloses rich behavioral details: slicing semantics with 0-based end-exclusive indices, contains filtering, include_textboxes behavior, textbox-only mode with box_index expectations, file-mode restrictions, and live-document behavior. This substantially exceeds what annotations provide.

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

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

The description is dense and information-rich, with the primary return shape front-loaded. Some clauses are terse to the point of requiring careful parsing, but every sentence contributes meaningful guidance with no filler.

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

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

Given the output schema exists and the complexity of the tool, the description covers the return shape, parameter semantics, mode differences, textbox special cases, and sibling routing. An agent has enough context to invoke the tool correctly in both file and live scenarios.

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 only 14%, so the description carries the parameter-documentation burden. It explains start/end indexing, end-exclusive slicing, contains filters, include_textboxes vs textbox modes, and live/file behavior. This compensates well for the sparse schema descriptions.

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

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

The description opens with a specific verb and resource: 'Read body paragraphs as [{index, text, style, ...}] with effective styles.' It clearly distinguishes itself from siblings by noting that equations are handled by list_elements and orientation by get_document_view, so the tool's scope is unambiguous.

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

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

The description provides clear context for when to use this tool and routes alternatives: equations go through list_elements, and orientation goes through get_document_view. It also explains mode-specific behavior for live vs file documents, though it does not enumerate all sibling exclusions explicitly.

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

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

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?

Annotations are minimal (only flags), so the description carries the behavioral burden. It discloses auto-backup, atomic save, live editing behavior, stale target refusal with remediation, and track/author recording. This goes well beyond annotations and gives an agent concrete expectations about side effects and failure modes.

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 efficient, using semicolons to pack multiple facts. It leads with the core action and item structure, then layers on constraints and behaviors. It's not overly verbose, though the density might require careful reading.

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

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

For a complex tool with 9 parameters and low schema coverage, the description covers most essential aspects: location, paragraph structure, heading behavior, formatting options, track/author, backup, live editing, and batch alternative. Minor ambiguities remain (e.g., exact meaning of 'stale text-selector target'), but overall it provides enough to call the tool correctly.

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

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

Schema description coverage is only 11%, so the description must compensate. It explains the structure of paragraphs items (text, style, formatting, heading_level, paragraph_format), semantics of heading_level (1-9, 1=outline 0), paragraph_format keys, inherit_format/copy_format_from behavior, track and author, and location default. Nearly all parameters are meaningfully described, far exceeding schema coverage.

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 inserts paragraphs, and describes the item structure and location parameter. It doesn't explicitly differentiate from sibling insert tools (e.g., insert_list, insert_break), but the purpose is unambiguous given the resource (paragraphs) and action (insert).

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

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

It provides clear context: location omitted means document end, file-mode-only constraints for certain features, and it explicitly points to apply_edits for batch operations. It doesn't name sibling insert tools as alternatives, but the batch guidance and live-editing caveats give practical when-to-use information.

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 state readOnlyHint=false and destructiveHint=true, but the description discloses substantial behavioral detail: preview mode performs a dry-run 'without touching the file'; max_replacements 'aborts, changing nothing'; tracked changes record by author; auto-backup and atomic save are described; 'Live edits appear immediately as one Ctrl+Z step, unsaved until the user saves.' It also notes that 'tracked replaces never re-match their own markup.' This far exceeds what annotations provide, making the tool's side effects and safety behavior fully transparent.

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 not bloated. It starts with purpose, then systematically covers item structure, scope, preview, formatting, max_replacements, tracking, sibling alternatives, live editing, and backup. Each sentence adds a distinct piece of essential information for a complex tool. While it is longer than typical tool descriptions, the complexity justifies the length; no sentence is filler. It is front-loaded with core purpose before diving into details, so a slight deduction for verbosity, but structure is logical and efficient.

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 (10 parameters, nested objects, output schema), the description covers all critical aspects: input semantics, safety workflow, error abort conditions, tracking, backup, live editing, and alternatives. It also explains the output behavior via preview counts and match contexts, which complements the existence of an output schema. No essential information for correct invocation is missing. The description is remarkably complete for a tool of this sophistication.

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 schema description coverage at only 10%, the description must carry the weight, and it does. It explains the replacements array structure ('{find, replace, regex?}; scope: body | footnotes | headers | all'), preview behavior and return values, max_replacements semantics ('aborts, changing nothing'), find_formatting restrictions and its mode compatibility, track and author usage, and backup=True default with 'backup=False skips rotation.' Even the live parameter is inferred through 'Live edits appear immediately as one Ctrl+Z step' and 'live:true' output references. The description effectively documents every parameter beyond what the sparse schema provides.

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 leads with 'Batch find/replace, safe across Word's fragmented runs,' a specific verb+resource pairing that immediately establishes the tool's core function. It then details the item structure and scope options, and explicitly distinguishes itself from the sibling set_paragraph_text by saying it rewrites whole paragraphs when a find string is unwieldy. This gives an agent a precise and unambiguous understanding of what the tool does and how it differs from related tools.

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

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

The description provides explicit alternatives and conditions: 'Sibling: set_paragraph_text rewrites one whole paragraph when a find string would be unwieldy' and 'For anchor-scoped edits, use apply_edits.' It also recommends a safe workflow: 'preview=true dry-runs... review, then rerun with max_replacements set to the previewed total.' This goes beyond vague context and tells the agent exactly when to use this tool versus alternatives, and how to use it responsibly.

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=false, destructiveHint=true, and idempotentHint=true. The description adds valuable context: 'Auto-backup; atomic save' reveals persistence guarantees, 'track records changes by author' indicates change-logging behavior, and 'Cell TEXT only' declares a hard constraint. It also explains live vs. file merge behavior. These insights go beyond the annotations and help the agent anticipate side effects. Not quite a 5 because it doesn't fully detail failure modes or what happens on validation errors, but it is strong.

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 compact. It packs multiple distinct facts into a few sentences using semicolons and parentheticals, front-loading the core purpose. There is minimal fluff and every sentence adds information. It is slightly overloaded with mode syntax inline (e.g., 'block={origin:{row, cell}, values:[[...]]}') but remains readable. A 4 because it could be broken into clearer bullets for extreme readability, yet it is far from 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?

For a tool with 9 parameters and low schema coverage, the description covers the essential context: modes, required parameters implied by examples, alternatives, limitations, live/file semantics, backup and atomicity, and batching. An output schema exists, so return values need no explanation. The agent has virtually everything needed to call it correctly, including edge cases like vertical merge refusal. This is a model description for a complex tool.

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

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

Schema description coverage is only 11%, so the description must compensate. It does: it explains the structure of 'edits' as [{row, cell, text}], 'block' as {origin, values}, and 'nested' as {row, cell, index}. It also clarifies that 'track' records changes by author and that 'live' has mode semantics. This provides meaning beyond the bare type definitions, though it doesn't exhaustively document every field in the array/object parameters (some nuance remains in the schema).

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

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

The description opens with a specific verb and resource: 'Write many table cells in one call.' It clearly distinguishes this from sibling tools by explicitly stating what it does NOT do (formatting via format_cells, properties via set_table_properties) and naming the batch alternative (apply_edits). An agent immediately knows the scope and how it differs from other cell/table tools.

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

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

The description gives concrete when-to-use and when-not-to-use guidance: it names format_cells for shading/bold/alignment, set_table_properties for widths and repeat-header, and apply_edits for batches. It also clarifies mode-specific behavior (live refuses vertical merges; file mode is merge-aware), so the agent knows which mode to choose based on the need.

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

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

Annotations already carry idempotentHint and destructiveHint, so the description earns credit for adding context: auto-backup, atomic validated save, serialized live editing, and refused features in live mode. The outline_level 'never changes the look' note is a non-obvious behavioral disclosure that materially prevents mis-calls.

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

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

Front-loaded with purpose and selection forms, then keys, then caveats, then routing. The keys list is long but necessary because the formatting schema is an open additionalProperties object. The live-mode sentence is slightly jumbled with parentheticals, 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?

Covers the main gotchas for a destructive mutation tool: backup, atomicity, live-mode restrictions, and the outline_level trap. Output schema exists, so return-value details need not be described. Minor gap: error/failure behavior beyond 'validated save' is not discussed, but the description is strong overall for a 7-parameter tool with minimal schema coverage.

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

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

Schema coverage is only 14% (only 'live' is described), so the description must compensate. It adds the mutually-exclusive indices/start-end selection semantics, the formatting object's key list, and critical value semantics for outline_level (0-8, null removes, off-by-one from heading_level). It does not detail value types for each key, but the key list plus the open formatting schema makes this solid.

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 ('Set paragraph formatting on a batch') and scopes the operation precisely with the selection forms (indices vs start/end) and the formatting keys. It also names apply_edits as the sibling it is not, making the differentiation explicit.

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

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

Gives explicit routing guidance ('For batches, use apply_edits'), the 'exactly one form' constraint, and the live-mode conditions with what is refused ('shading/borders/tab_stops refused live'). It does not contrast with format_text or apply_style, but the core when/when-not guidance is present.

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

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

Beyond the destructiveHint and idempotentHint annotations, the description discloses meaningful behavior: index shifting after edits, the expect guard to avoid wrong-paragraph hits, auto-backup behavior, atomic validated saves, and serialized live edits on open documents. No contradiction with annotations was found.

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

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

The description is dense but every sentence earns its place: main operation, addressing strategy, safety guard, backup behavior, live-editing caveat, 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, the description covers the essential operational concerns: how to locate the paragraph, how to avoid index-shift mistakes, what to verify, backup semantics, live behavior, and tracked-revision refusal. With an output schema present, return-value details need not be duplicated here.

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

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

With schema description coverage at only 17%, the description compensates strongly: it defines the location object forms ({paragraph: N}, {search: ...}, {outline: ...}), explains expect as a safety substring, and clarifies backup=False skips rotation. This adds real meaning beyond the bare schema.

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

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

The description opens with a specific verb and resource: "Replace one paragraph's full text." It further clarifies scope by noting that style and base formatting are preserved, which distinguishes it from formatting-focused siblings like set_paragraph_format and batch-oriented 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 explicitly names the alternative for batches: "For batches, use apply_edits." It also gives practical usage context: how to address the paragraph via location objects and when live edits are refused on tracked-revision paragraphs.

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