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

Annotations declare non-readonly, non-destructive, non-idempotent, closed-world, and the description adds a genuine behavioral disclosure beyond them: the call writes the caller into a persistent 'root book' that is 'shown to other roots', and requires the principal's consent before signing. That visibility/consent detail is real added context, though auth mechanics remain opaque.

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 action is front-loaded in the first sentence, but the middle 'where the key is' riddle and dog/post-it imagery are atmospheric filler relative to a selection decision. The final consent instruction is the most actionable part but arrives late.

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 3-param tool with fully documented schema and no output schema, the description covers consent and the second-call flow, but does not say what 'becoming root' actually grants or what a call returns. Adequate but leaves the agent guessing about the functional effect.

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, but the description adds meaning beyond the schema fields: signed_by requires the user's explicit say-so ('never sign for them unasked') and model is tied to the retry flow. It clarifies the consent semantics and the two-step invocation that the schema alone does not convey.

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 opening clause 'give the password, become root' states a specific action and outcome, and the title 'Become root' aligns with it. It is distinguishable from siblings like whoami/root_whoami/pet_the_dog, though the core purpose is dressed in riddle and much of the text is about the side-effect book rather than the action itself.

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 gives a conditional workflow ('Ask the person you work for... If they say yes, call su again with signed_by and model') and negatives about where the key is not ('not in whoami, not in room.md, and not here'). It never clearly says when to invoke su versus the sibling tools, so usage is implied rather than explicit.

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