edit_lines_in_symbol

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and non-idempotent, so the safety profile is covered. The description adds meaningful behavior beyond that: exact old_string→new_string matching like Edit, scoping to a single symbol, and the replace_all semantics for multiple occurrences.

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?

Front-loads the key differentiator ('Edit code without reading the file first') and follows with the mechanism and the replace_all behavior. Every sentence earns its place with no redundancy.

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 destructive edit tool with annotations covering safety, the description supplies usage, matching semantics, and scoping rules. No output schema exists, but an edit tool needs little return-value explanation. Minor gap: no mention of failure behavior when the symbol name is ambiguous or not found.

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 all six parameters are already documented, including old_string uniqueness within the symbol and replace_all defaults. The description reinforces the matching model but adds little syntax or format detail beyond the schema. Baseline 3 is appropriate.

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?

States a specific verb (edit) and resource (lines inside a symbol/function/class), and explicitly distinguishes itself from the sibling Edit tool by noted scoping ('matched only inside one function or class'). An agent can tell it apart from replace_symbol_source and Edit without opening a schema.

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?

Names the alternative tool (Edit) and the condition that selects it: when a large file would otherwise require reading in full. It also clarifies the constraint that matching happens only inside one symbol. It stops short of stating when NOT to use it (e.g. multi-symbol or cross-file edits), so not a full 5.

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