script_patch

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

No annotations provided, but the description effectively discloses important behaviors: exact byte match (whitespace significant), triggers filesystem scan, and is not undoable via Ctrl+Z. It does not detail permissions or potential destructive effects beyond the edit, but the presence of an output schema reduces the need to explain return values.

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 concise and well-structured, with the main purpose front-loaded followed by key details. Every sentence adds value, resulting in no wasted words.

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 the complexity of 5 parameters and the presence of an output schema, the description covers the main behaviors and side effects. However, it could be slightly more complete by clarifying the exact nature of the 'filesystem scan' or potential cost, but overall it is adequate.

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%, so baseline is 3. The description adds meaning beyond the schema by explaining that old_text must be unique unless replace_all is true, new_text can be empty to delete, and replace_all replaces every occurrence. This clarifies usage beyond the schema's property descriptions.

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 clearly states it performs an 'anchor-based string-replace edit on a .gd file' using specified old_text and new_text. It distinguishes itself from sibling tools like script_create or script_manage by focusing on editing existing scripts via string replacement.

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 usage for modifying .gd files but does not explicitly state when to use this tool versus alternatives. It mentions failure conditions (multiple matches unless replace_all=True, zero matches) but provides no comparison to sibling tools or guidance on when not to use.

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