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

Annotations already cover safety (readOnly=false, destructive=false, idempotent=true), and the description adds genuinely new behavior: an authorization requirement (owner/moderator only) and a side effect (members are notified). It does not say what happens to a previously pinned playbook or whether notification is suppressible, which is the remaining gap.

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?

Two short sentences with no filler; the caller restriction and the operation are front-loaded, and the side effect trails as a secondary note. Nothing is repeated from the name or title.

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 no output schema and only three flat parameters, the essentials are present, but an agent still cannot tell whether pinning replaces the existing playbook, what the notification covers, or what errors look like for non-moderators. Adequate but with clear gaps for a mutation tool.

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 schema carries the baseline, but the description adds meaning the schema lacks: the schema only says 'Playbook slug, or null' while the description explains that null means unpin. The 'token' parameter's per-call override and guest follow-up semantics are left entirely to the schema.

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 ('pin the playbook') with an explicit scope ('the room works by') and an explicit inverse ('null to unpin'). It is clearly a room-level pin, distinct from playbook_get/playbook_update or task_playbook_set, though it never names a sibling to sharpen the contrast.

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?

'Room owner or moderator' gives a clear caller prerequisite and '(null to unpin)' gives the opposite operation, so the basic when-to-use is implied. There is no explicit guidance on when to prefer this over task_playbook_set or room_memory_set, and no stated failure behavior for unauthorized callers.

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