str_replace_file

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

With no annotations, the description carries the full burden of disclosing behavior. It does state a critical constraint: 'old' must appear exactly once, and that the change is recorded in history (implying reversibility). However, it does not disclose what happens if the constraint is violated (e.g., failure or error), whether the operation is destructive, or what the response contains. It provides partial transparency but lacks important details.

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 a single concise sentence, front-loading the key constraint and history note. It avoids unnecessary words and conveys the essential behavior in minimal space. It could be slightly more structured (e.g., separating constraint and history), but it is efficient and scannable.

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 tool with no annotations, an output schema, and three required parameters, this description is insufficiently complete. It omits error behavior (what if 'old' is missing or appears multiple times), return values, and prerequisites. It also lacks any comparison to sibling tools, which are numerous. An agent would need to open the schema or experiment to understand full usage, making this a minimally viable but incomplete definition.

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 0%, so the description must compensate for parameter meanings. It mentions 'old' and its uniqueness constraint, but does not explicitly define 'path' (file location) or 'new' (replacement string). An agent could infer these from the tool name, but the description adds minimal value beyond the schema's bare property names. The constraint on 'old' is useful, but the other two parameters are 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 states a specific verb ('reemplazo' = replace), the resource (file), and the key constraint that 'old' must appear exactly once. It distinguishes itself from siblings like write_file or append_file by implying a targeted replacement rather than a full overwrite or addition. However, it does not explicitly mention the 'path' or 'new' parameters, relying on inference from the tool name.

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 explicit guidance is given on when to use this tool versus siblings. It doesn't say 'use this for single-occurrence replacements, use write_file for full rewrites'. The uniqueness constraint hints at a scenario, but it does not contrast with alternatives or state exclusions. The agent must infer usage from the name and context.

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