Search and Replace

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

Beyond the annotations, it discloses substantial behavior: atomic saves, two-slot backup, preservation of the first run's formatting, inclusion of SmartArt node text, skipped overlapping fields, and the exact semantics of live='auto'/'force'/'off'. This meaningfully enriches the agent's model of the operation and is consistent with destructiveHint=true.

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 is information-dense and the core purpose is front-loaded. The text is somewhat telegraphic and mixes multiple caveats into flowing sentences, but it remains appropriately sized for a tool with this many parameters and behaviors.

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 formatting safety, SmartArt behavior, skipped fields, atomic saves with backups, locked-file modes, and sibling alternatives. Given that an output schema exists and the description already provides a full behavioral picture, nothing essential is missing 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?

The schema contains no descriptions, so the description carries the burden. It adds real meaning for regex, live, and backup, and file_path/find/replace are inferable by name. However, scope, match_case, and include_notes are not explained, leaving important parameter behavior undocumented.

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 'Deck-wide find and replace,' which names a specific verb, resource, and scope. It further distinguishes itself by noting fragmented-run safety, SmartArt inclusion, and explicitly routing bulk cell rewrites to set_table_cells and batches to 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?

It gives explicit alternative conditions: 'Bulk cell rewrites: set_table_cells (tables-charts pack)' and 'Batches: apply_edits.' It also defines when each live mode applies to locked files, so an agent can decide whether this is the right tool and how to invoke it safely.

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