rename

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

The description explicitly warns that 'This tool will update the JCAD document at the given jcad_path', disclosing the mutation side effect. It also notes the return value (the document itself). With no annotations present, this warning carries the transparency burden, but it does not cover failure modes or conflict handling.

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 compact and includes only necessary elements: purpose, parameters, return value, and a safety warning. It is not overly verbose, though the formatting with extra whitespace and indentation could be tighter.

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 simple rename operation, the description covers the action, all three parameters, the return value, and a critical warning about document mutation. It does not discuss edge cases like nonexistent old names or naming constraints, but such details are secondary given the tool's straightforward nature.

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?

The description provides per-parameter explanations for old_name and new_name in the :param lines, and the warning clarifies jcad_path as the target document location. Since the schema has no descriptions (0% coverage), this addition is valuable and compensates for the lack of structured documentation.

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 action ('Rename') and the target ('an object in the document'), providing a specific verb and resource. It distinguishes this tool from siblings such as remove or add_box by focusing on renaming, and the JCAD document context is reinforced by the warning.

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 instructs the agent to first use 'get_current_cad_design' to understand the current document state, which is a clear and important prerequisite. It does not explicitly compare with alternatives, but no sibling tool handles renaming, so the implicit usage context is sufficient.

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