docx.replace_text

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

No annotations are provided, so the description carries the full behavioral disclosure burden. It only states 'replace' and gives no information about mutation effects, whether formatting is preserved, whether headers/footers are affected, or how the tool behaves with regex patterns.

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 short and front-loaded, but it is under-specified rather than efficiently concise. One vague sentence does not earn its place when five parameters and two enums need contextual explanation.

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 five parameters, two enum fields, no output schema, and no annotations, this one-line description leaves major gaps: match behavior, regex semantics, where scope, all-occurrence behavior, and error conditions are all unaddressed. An agent would struggle to call this tool correctly without inspecting external documentation.

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 input schema already describes docId, match, and replace, but the description adds no meaning for the undocumented mode and where parameters. It does not clarify defaults, the difference between literal and regex matching, or the effect of 'document', 'headers', 'footers', and 'all' scopes.

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 phrase 'Replace text in document' states a clear verb and resource, but it does not specify scope or behavior, such as whether replacement applies to all occurrences or only first matches. It also fails to distinguish this tool from sibling docx.text_run_replace, which is also a text-replacement operation.

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?

No guidance is given about when to choose this tool over docx.text_run_replace, docx.find, or docx.text_find_locations. There is no mention of suitable contexts, prerequisites, or when the regex/literal modes should be used.

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