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

Annotations already carry readOnlyHint=false and destructiveHint=true, and the description is consistent with them rather than repeating them. It adds genuine behavioral context beyond the annotations: rewording 'changes what they SAY', redistilled rules 'arrive as proposed for you to rule on', the hourly rate limit, and the 'decisions permission' requirement. It does not elaborate on what exactly gets destroyed or whether a reword is reversible, but the added context is substantial.

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 a dense but efficient paragraph that front-loads the core purpose before moving to modes and constraints. The background sentence explaining rules and cromanion_decide's role earns its place because it defines domain vocabulary used throughout, and the rate-limit/permission sentences are brief. It could be marginally tighter, but no sentence is wasted.

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 two-mode tool with 5 parameters, the description covers purpose, mode selection, parameter combinations, the source of ids, the rate limit, and the permission requirement — and an output schema exists, so return values don't need explanation. The only gap is the unelaborated destructive hint: the description doesn't say whether rewording an approved rule re-enters the proposed state or permanently overwrites it, which would strengthen completeness for a destructive call.

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 coverage is 100%, so the baseline is 3 with the schema doing the heavy lifting. The description adds value on top by specifying parameter interactions not in the schema: the mutually exclusive relationship between redistill and ruleId ('Send redistill: true instead'), and the combinability of ruleId with condition and/or recommendedAction. This interaction guidance is exactly what an agent needs to invoke the two modes correctly.

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 opens with a specific dual-purpose statement — 'Reword a distilled rule, or ask for a fresh distillation' — with a clear verb and resource, and then defines what a rule is and how it relates to siblings (cromanion_decide approves/pauses, cromanion_config provides ids). It distinguishes both modes from one another and from the sibling tools' responsibilities, so an agent can tell exactly what this tool does.

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 gives explicit conditions for each mode: send a ruleId with condition and/or recommendedAction to reword, send redistill: true to distil fresh rules, and states that ids come from cromanion_config while approval happens in cromanion_decide. It also discloses the rate limit ('one distillation an hour') and the required permission. It stops short of an explicit 'use X instead' exclusion statement, but the routing to siblings is clear enough.

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