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

Annotations already mark it destructive and non-idempotent, and the description goes well beyond that: rule text and history are preserved, retirement is logged in Loop Activity, an already-retired rule returns changed: false, running iterations keep their original prompt. This is exactly the extra context annotations cannot supply.

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-loaded with the action and scope, then layered: prerequisites, edge case, irreversibility, concurrency note. Every sentence carries distinct information; nothing is redundant with the schema or annotations.

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?

Output schema exists so return values need not be documented, yet the description still flags the changed: false case. For a destructive, irreversible mutation tool it covers prerequisites, side effects, logging, reversibility, and the restore path — nothing an agent needs is missing.

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 0%, so the description must compensate and it only does so partially: it gives provenance for rule_id (from list_steering_rules) but says nothing about expected format for project_id or rule_id. Baseline 3 for a low-coverage two-parameter schema is fair.

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 and resource ('Retire one steering rule') plus the exact scope ('so no later iteration prompt carries it'), which separates it cleanly from approve_steering_rule and list_steering_rules. An agent knows what the operation does without opening the 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?

Explicitly says to pass the rule id from list_steering_rules, that it works for active or pending rules including auto-protected retro kaizen, and names the alternative path for reversal: 'There is no un-retire: to bring a convention back, submit it as a new Request.' When/when-not/alternative are all covered.

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