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

Beyond the annotations, it explains that live edits stay unsaved until com_save_document, that most com_ ops use a private hidden Word and do not alter the source file, and that com_refresh_fields is the exception because it saves in place. It also states that closing with save=false discards unsaved changes, which is exactly the kind of destructive 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?

The description is long but front-loads the purpose, key behavioral constraints, and sequencing before listing operations. It is dense and earns most of its space, though the first few op lines duplicate content already present in the schema enum description.

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

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

For a 14-op, high-complexity tool with no output schema, it supplies the critical context: which ops use hidden Word, which mutate the source file, which require Word to be open, and how to sequence live edits and saves. It also points to word_help for argument details, so the description is complete enough for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds useful meaning: file_path is required unless an op names other paths or reads no document, and unknown args keys are refused. The op argument list is partially duplicated in the schema's op enum description, which keeps this from a 5.

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

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

The description opens with a specific scope: 'Needs Microsoft Word itself' and lists the exact Word-application operations it owns, from saving open documents to PDF import/export and live repair. It explicitly separates this tool from word_edit and word_read, so an agent can distinguish it from siblings without opening their schemas.

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

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

It names the alternatives and when to use them: text edits go through word_edit and reads through word_read. It also gives sequencing rules for live work, saying to enable track changes before editing and save last, which tells the agent how to order calls correctly.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, and the description goes well beyond them: "Writes only the files named in args", "an existing destination is refused unless overwrite=true", "purge is a dry run unless dry_run=false", "all default OFF, none enabled refuses", "unknown keys are refused", "only the parameters given change". These refusal, dry-run, and no-op-default semantics are exactly the mutation-safety context an agent needs and are not derivable from the annotations.

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

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

Front-loaded with the scope sentence, then a dense but uniform per-op table — appropriate for a 15-op dispatcher, and every line earns its place. Minor cost: the enumeration is split between the description and the op parameter's description ("More ops follow, in the same format"), forcing the agent to read two places, and terms like "live" and "backup" are referenced before being introduced.

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 multi-op writer with no output schema and an open args object, the definition covers all 15 ops, the path convention, and the mutation-safety profile. Gaps are small: the args-key contract is delegated to word_help, and return/result behavior for the file-writing ops is left implicit.

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

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

Schemas cover the top-level op/args shape, but args is an untyped additionalProperties object — the description supplies the real semantics: required vs. optional per op and what each does ("insert_document(target_path, source_path; opt location formatting)"). It also explains the shared file_path convention and that "file_path, live and backup are not repeated; word_help shows them", which is meaning the schema cannot provide.

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?

"Whole files: create, copy, assemble, split, templates, mail merge, backups..." states the resource and scope with a specific verb list, and the immediate contrast "Edits inside one document belong to the other tools" carves out the boundary against word_edit/word_format. An agent can route between this and its nine siblings from the first two sentences alone.

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

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

The when-not rule ("Edits inside one document belong to the other tools") plus the whole-file scope is an explicit exclusion, and per-op lines describe the situation each op serves ("the chapter-merge tool", "the inverse of ... merge"). It stops short of naming the specific sibling an agent should use for in-document edits, leaving that inference to the agent.

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=true annotation it discloses the actual safeguards: every edit to a closed file backs it up first, saves atomically, and a failed validation changes nothing; a document open in Word is edited live and stays unsaved until word_app com_save_document, and ops with no live route refuse. It also explains tracked-change semantics (track=true) and authorship (omit author to sign with the user's name, author="assistant" to sign as an AI). This is exactly the extra context the annotations cannot carry.

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?

Structure is logical and front-loaded: purpose, sibling boundaries, escaping, track/author semantics, backup and live-edit behavior, addressing rules, then a per-op line format. It is long and dense, and the trailing 'More ops follow... in the op parameter's description' is a meta-instruction, but nearly every sentence carries non-redundant operating information for a multi-op dispatcher.

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

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

For a 9+-op dispatching tool with no output schema, it covers addressing, safety, live-vs-closed files, and per-op argument shape thoroughly. It does not say what the ops return or how success/failure is reported beyond 'a failed validation changes nothing,' leaving a modest gap for a tool with varied per-op results.

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

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

Schema coverage is 100%, but the description still adds real meaning: paragraph indices are 0-based, count body paragraphs only, exclude tables, and are visible via get_text/get_outline; an insert at {"paragraph": N} goes after paragraph N, with position 'before' putting it in front; and in any written text \n is a line break and \t a tab. That resolves ambiguities the enum/schema alone would leave open.

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

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

The opening line states a specific verb+resource (change body text) and enumerates the covered operation families: insert, rewrite, delete, find/replace, breaks, redaction, apply_edits, anchor stamping. It also draws explicit boundaries against siblings: 'Tables and lists are word_structure; styles and formatting are word_format,' so an agent can distinguish it without opening another schema.

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

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

It gives concrete routing rules: use after_heading/search/anchor 'instead of a number' when a heading or phrase marks the spot, use search_and_replace to add words inside an existing paragraph, and use redact_text rather than search_and_replace for sensitive removal. It names what to do when redaction refuses ('ask the user what to use instead'), and it routes live-file work to word_app com_save_document, so when/when-not/alternatives are all explicit.

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

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

Annotations only say destructive/non-idempotent; the description adds materially more — every edit backs the file up first and saves atomically, define_style replaces only the properties given (patch semantics), and apply_manuscript_format lists rather than applies guide-left-open choices. The live-document refusal rule is exactly the kind of behavioral fact annotations cannot express.

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

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

Front-loaded summary followed by a compact one-line-per-op reference block; nearly every clause carries information. Minor friction: the aside 'file_path, live and backup are not repeated; word_help shows them' is terse to the point of ambiguity, and the parenthetical 'format_text (formatting, not case)' sits in tension with the op line that says format_text can 'change case.'

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

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

For a six-op router tool with a generic args object and no output schema, the description supplies per-op argument contracts and hazard handling, which is most of what an agent needs. The remaining gap is return values: only apply_manuscript_format's behavior ('choices the guides leave open are listed') hints at what comes back; the other ops' responses go unmentioned.

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?

Top-level schema coverage is 100% but the args object is opaque (additionalProperties: true), and the description fills that gap by marking required vs optional per op. It also explains semantics the schema cannot: style_id is an id (Heading1) not a display name, and set_paragraph_format takes indices OR start/end, 'exactly one form.'

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

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

Opens with a specific scope statement ('How text looks: apply or define styles, character and paragraph formatting, heading levels and manuscript format') and immediately demarcates it from word_edit ('To change the words themselves use word_edit'). The six enumerated ops make the surface area unambiguous without opening the schema.

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

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

Explicitly names alternatives (word_edit for text content, word_help for arguments) and gives a hard usage constraint: format_text and set_paragraph_format work on a document open live in Word, while 'the other ops refuse it.' No guidance, however, on when to prefer change_heading_level here versus structure-related ops in word_structure, so the sibling boundary against word_structure is left to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description still adds real context, notably 'Reads no document' (so an agent knows it is side-effect-free with respect to document state) and what each mode returns. It doesn't cover caching or size of the returned listing, but that is minor.

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

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

A single dense paragraph, front-loaded with the read-only framing and the primary trigger, then the three mode behaviors. Every clause carries information; no filler or restatement.

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

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

With no output schema, the description compensates by describing what each invocation mode returns (tool/op listing, op arguments + example + owning tool, location explanation). An agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is already 100%, and the description goes further by stating the behavioral consequence of each parameter: omitting `op` lists everything, supplying it yields arguments + an example call + the running tool, and `topic='location'` explains the location object. That is meaning beyond the schema's field descriptions, though it doesn't add format details for op names.

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

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

It states a specific function: reading help/metadata about the word tools and their ops, not touching documents. It clearly distinguishes itself from the sibling tools (which all act on documents) via 'Reads no document.' The only slight weakness is that 'help' alone is generic, but the description resolves it by enumerating what help content it returns.

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

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

It gives explicit triggers ('when an op's arguments are unclear or after a BAD_PARAMS refusal') and maps each invocation mode to an outcome: no args lists every tool and op, `op` returns that op's arguments plus an example and owning tool, `topic='location'` explains the location object. Nothing is left to inference about when or how to call it.

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

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

Goes well past the destructiveHint annotation: every edit "backs the file up first and saves atomically," ops "refuse a document open in Word," field codes outside a safe allowlist are refused, export_images refuses to overwrite existing files and does not modify the document, set_image leaves unnamed properties untouched, and set_chart_data requires the series count to stay the same. These are exactly the mutation-side effects an agent needs before committing.

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 summary, then a consistent `name(required; opt optional): what it does` format that scans quickly despite its length. The meta-lines ("file_path, live and backup are not repeated; word_help shows them", "More ops follow... in the op parameter's description") add navigation cost but earn their place by not duplicating shared arguments.

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

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

For a 2-argument multiplexer over 12 heterogeneous operations with no output schema, coverage is strong: safety behavior, argument shapes, id sources ("image_id from list_elements", "box_index from get_text(textbox=true)") are all given. The remaining gap is return values — nothing says what insert_image or insert_chart yields, so the agent cannot chain ops within a session.

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

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

Schema coverage is 100%, but the schema's `args` object is a generic bag, so the description is doing the real work: it marks required vs optional per op and adds behavioral defaults ("inline by default," "aspect ratio is kept," "anything not named stays"). It covers 8 of 12 ops and defers the rest to the op enum's description, which is disclosed but splits the documentation an agent must read.

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

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

Opens with a concrete resource enumeration ("images, charts, equations, text boxes, hyperlinks, fields, form fields and content controls") and each op line states a specific verb plus effect. It explicitly routes siblings: "Plain text is word_edit and tables are word_structure." An agent can place this tool against all nine siblings without opening a schema.

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

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

Sibling boundaries are stated for the two most likely confusions (word_edit for text, word_structure for tables), and each op line implies the situation it serves. There are no explicit when-not-to-use exclusions or prerequisites beyond the open-file refusal, so it falls short of a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description is consistent with them while adding non-obvious constraints: some ops read the document open in Word live, get_document_view reads the last saved state, and other file reads require the file closed in Word. It also flags Word busy/blocked-by-dialog states and unsaved changes via com_word_status.

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

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

Very long but every line is a distinct op with its arguments and return shape; nothing is padded. The critical facts (read-only, the mutating siblings, live vs saved state) are front-loaded before the op table, and at ~23 ops the length is proportionate.

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 23-op dispatcher with no output schema, the description covers purpose, routing, state requirements, per-op arguments, and even return shapes for the main ops (get_text's [{index, text, style, ...}], list_elements' ids). The remaining ops are handed off explicitly to the `op` parameter's schema description in the same format, so nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, but the schema only exposes a bare `op` enum and an `args` bag; the description supplies the real argument semantics per op (e.g. start/end are paragraph numbers with end exclusive, regex vs query in find_text, detail="full" shows revisions and comments). It also states that file_path, live and backup are shared and where to find them.

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

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

Opens with a specific verb set (inspect, search, list, count, check) and the exact resource (.docx), and immediately names eight sibling tools that do the mutating work. The live-vs-saved-state sentence further partitions it from its own ops, so an agent can place the tool without opening the schema.

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

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

Explicit when/when-not: 'Never changes a file. To change anything use word_edit, word_format, word_structure, word_media, word_review, word_references, word_document or word_app.' It also routes within the tool — com_word_status 'use before live edits', detect_citation_system 'run it before citation work', get_document_view as the low-token alternative to get_text.

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

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

The annotations already mark this as destructive and non-idempotent, and the description adds important behavior: every edit backs up the file first, saves atomically, and refuses documents open in Word. It also explains that field results are deferred until Word updates fields, which is crucial for expectation setting.

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 its length, the structure is efficient and front-loaded: domain summary, safety/field-update behavior, then compact op definitions. The line-per-operation format is appropriate for a multi-operation tool and avoids wasted prose.

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 13-operation tool with no output schema, the description covers selection, mutation safety, field-update timing, and most op semantics well. It is slightly incomplete on return values and relies on word_help for some shared argument details, but the overall operational picture is strong.

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

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

Schema coverage is 100%, so the schema carries the formal parameter burden, but the description adds substantial op-level meaning for arguments, such as image_id usage, bookmark targets, hidden XE index fields, and which arguments are required versus optional. It does defer some common path details to word_help, which keeps it from being fully self-contained.

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 domain: generated lists and scholarly apparatus such as TOC, footnotes, captions, bookmarks, cross-references, index, citations, bibliography, and Zotero. It clearly distinguishes this from sibling word_edit by stating that plain text editing belongs there.

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

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

It gives explicit routing guidance: plain text is word_edit, and field results populate through Word field updates such as word_app com_refresh_fields. It also warns that these operations refuse a document open in Word, which is a key usage constraint.

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 flag destructiveHint=true and idempotentHint=false, but the description adds material context: resolve_revisions and prepare_for_submission are undoable only from the automatic backup, anonymize_for_review writes a private mapping file and flags prose for human checking, and all ops refuse documents open in Word. That is exactly the kind of irreversibility and side-effect disclosure the annotations alone cannot 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?

Structure is strong: an overview sentence, sibling routing, a warning about irreversibility, then a consistent 'name(required; opt optional): what it does' legend with shared args factored out. The opening sentence is a dense run-on packing eight operations, which costs a little readability, but no line is filler.

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

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

For a multi-op dispatcher with no output schema, the definition covers purpose, alternatives, preconditions, irreversibility, per-op arguments, and a pointer to word_help for the shared file_path/live/backup args and for further ops. Nothing an agent needs in order to pick and invoke an op is missing.

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

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

Schema coverage is 100% and the args object is freeform, so the description carries the real burden — and it does, listing per-op required and optional arguments (action, comment_id, author, mapping_path, accept_revisions, baseline, etc.) with semantics such as leaving author out to sign with the user's own name. This goes well beyond the schema's generic args 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?

The opening sentence names a specific resource (comments and tracked changes in Word documents) and a concrete set of verbs (add, reply, resolve, delete, accept, reject, anonymize, clean). It explicitly distinguishes itself from siblings by naming word_read for reading and word_edit with track=true for tracked edits, so an agent can route without opening either schema.

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

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

Explicit routing is given: 'To read comments or tracked changes use word_read; to make tracked edits use word_edit with track=true.' It also states a hard precondition ('refuse a document open in Word') and names live_set_track_changes as the alternative for open documents, covering when-to-use and when-not.

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, it discloses that every edit backs up the file first and saves atomically, and that all ops except set_cells refuse a live Word document. It also notes destructive actions like deleting a whole table and replacing the whole header/footer part, which is valuable behavioral context for a destructiveHint=true tool.

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

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

The description is long but warranted for a 15-op tool. Purpose and critical behavioral constraints are front-loaded, and the one-op-per-line catalog is structured for scanning; the note that remaining ops appear in the op parameter description prevents duplication.

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 multi-operation mutation tool with no output schema, the definition covers invocation details, safety behavior, live-document constraints, and op-specific argument requirements. The split between main description and op enum description is clearly signposted, leaving no obvious gap for an agent to call it correctly.

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

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

Although schema coverage is 100%, the description adds operation-level semantics: required versus optional arguments for each listed op, meaning of values like ref_type 'first', and refusal of extra arguments in modify_table_structure. It also correctly delegates file_path/live/backup details to word_help rather than repeating them.

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

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

The description names a specific resource and scope: tables, lists, page layout, sections, headers/footers, and page numbers. It distinguishes itself from the sibling word_edit by stating 'Body text is word_edit,' so an agent can route correctly without opening either schema.

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

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

It explicitly identifies the alternative for body text and gives a key usage condition: 'set_cells edits a document open in Word live; the other ops refuse it.' The operation catalog further clarifies when to use each op, including special cases like no section break being needed for a first-page header.

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