word_analyze

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

No annotations are provided, so the description carries full responsibility. It mentions returning a text index but does not explain the output structure or behavior beyond that. It also references a 'fmt_hints' parameter that is not part of the input schema, which is a behavioral inconsistency and leaves the agent uncertain about expected inputs and outputs.

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 not concise; it spends significant space detailing an addressing scheme and format hints that pertain to word_replace, not word_analyze. This irrelevant content detracts from the core message and makes the description longer than necessary.

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

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

Although an output schema exists, the description fails to explain how the tool is used or what the returned text index represents. It also introduces a non-existent parameter, making the description incomplete and inconsistent with the structured data. For a simple one-parameter tool, the description should be clearer.

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

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

The schema has a single 'path' parameter with zero description coverage, and the description does not clarify what 'path' means. Worse, the description introduces a 'fmt_hints' parameter that does not exist in the schema, actively misleading the agent about the available parameters.

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

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

The description states the tool 'Analyze a Word document structure' and that it 'Returns text index for word_replace', which is a specific verb+resource and distinguishes it from siblings like word_replace (which modifies) and word_read_document (which reads content). However, the subsequent addressing scheme and format hints sections are tangential to word_analyze and may confuse the reader.

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 that the tool is a precursor to word_replace by stating it returns a text index for that tool, giving some context. However, it does not explicitly say when to use this versus alternatives like word_read_document, nor does it provide exclusions or prerequisites.

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