record_edit

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

With no annotations provided, the description carries the full burden of disclosing side effects. It only says 'Record a code edit for version history tracking,' but does not explain what recording entails (e.g., whether it writes to a persistent store, whether it modifies files, or if any permissions are needed). This is a significant gap for a tool that likely has mutation behavior.

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 extremely concise, using two short sentences to convey the legacy status and a performance comparison. It is front-loaded with the 'Legacy' warning. However, it may be too brief for a tool with eight parameters, lacking necessary elaboration for safe use, but the conciseness itself is effective.

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 tool has eight parameters and no output schema, the description is incomplete. It does not explain the tool's behavior beyond recording an edit, nor does it mention any prerequisites, side effects, or edge cases. The 'Legacy' note is helpful but not sufficient for full contextual understanding, leaving significant gaps for an agent deciding whether to invoke it.

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%, with all eight parameters having explicit descriptions in the schema. The tool description adds no parameter-specific information, so it does not enhance the semantic understanding beyond the schema. Baseline of 3 is appropriate given the schema's completeness.

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 the tool's action ('Record a code edit') and its purpose ('for version history tracking'). While it doesn't explicitly differentiate from all sibling tools, the 'Legacy' label and the note about create_file_snapshot provide some distinction, making the purpose understandable.

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 provides clear usage guidance by labeling the tool as 'Legacy' and explicitly noting that 'create_file_snapshot is much faster.' This implies prefer the alternative while still allowing this tool for older workflows, giving a concrete comparison and implicit when-to-use guidance.

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