replace_regex

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It reveals the core replacement behavior and wildcard strategy, but it does not warn that this is a permanent file mutation, does not mention permission or irreversibility risks, and does not explain error behavior for multiple matches (though that is in the schema). For a mutation tool with no annotation safety hints, this is a significant transparency gap.

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 reasonably concise: two sentences of guidance plus an emphasized note. However, the all-caps wildcard warning is somewhat redundant because the same advice appears in the preceding sentence. The structure front-loads the core purpose and usage guidance well, but the emphatic note could be trimmed without losing meaning.

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 four parameters, an output schema, and no annotations, the description offers useful usage strategy but omits critical context for a mutation tool: no warning about permanent changes, no mention of failure modes (e.g., multiple-match error when allow_multiple_occurrences is false), and no explicit pointer to sibling tools for simpler replacements. It is not fully complete for safe and 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 description coverage is 100%, providing a strong baseline. The description adds meaningful guidance for the 'regex' parameter by suggesting wildcard usage and a compact form 'beginning.*?end-of-text-to-be-replaced,' which helps agents construct effective patterns. It does not add information for 'repl' or 'allow_multiple_occurrences,' but the schema already covers those well.

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 verb and resource: 'Replaces one or more occurrences of the given regular expression.' It clearly distinguishes itself from sibling symbol-level tools by stating it is 'the preferred way... whenever the symbol-level tools are not appropriate.' This makes the tool's purpose unambiguous and differentiates it from replace_symbol_body and similar tools.

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 explicitly says when to use it: 'preferred way to replace content in a file whenever the symbol-level tools are not appropriate.' It also provides concrete guidance on using wildcards and regex forms like 'beginning.*?end-of-text-to-be-replaced.' However, it does not explicitly name specific alternative tools or state clear when-not-to-use conditions beyond the broad 'symbol-level tools not appropriate' phrase.

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