Word Formatting and Styles

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.