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

The description discloses that subdecks, cards, and review history follow the deck to the new location, which is a key consequence. It also states that missing parent decks are created, and that duplicate names cause refusal rather than merge. This goes well beyond annotations, which only say readOnlyHint=false and destructiveHint=false, but don't specify 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?

Four sentences, each carrying necessary information, with the primary purpose front-loaded and edge cases after. No redundant wording.

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?

With an output schema present and clear annotations, the description does not need to cover return values. It covers all relevant execution details: path semantics, creation of parent, following subdecks, refusal conditions, and top-level behavior.

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 schema already covers both parameters at 100% coverage, but the description adds that new_name is a full path and that an intermediate parent is created if missing, which is not in the schema. This extra semantic clarifies the effect of the new_name value.

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 uses a specific verb ('Rename') and resource ('deck') and explicitly covers both rename and move operations. It distinguishes from siblings like delete_deck, archive_deck, and create_deck by stating the action and usage scenarios. The refusal conditions further clarify its scope (no merging, no self-nesting).

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?

It starts with 'Use when the user asks to rename a deck, nest it under another, or pull it out to the top level', giving explicit trigger conditions. The 'Refused if' sentence adds when-not constraints, though it doesn't name alternative tools. This is clear context without explicit alternative references, sufficient for an agent to decide.

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