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

Annotations already flag destructiveHint=true, readOnlyHint=false and openWorldHint=true, so the safety profile is covered; the description goes further by disclosing a real side effect agents cannot see in the schema — 'Every member is notified, and the result says how many.' It also adds a confirmation ritual for pinned posts. It stops short of saying which of the seven sub-actions are irreversible (e.g. cancel_meeting, finish_book) or whether a closed poll can be reopened, which would have earned a 5.

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 front-loaded with the actor and the action list, then moves to trigger examples, then to caveats, which is the right order for an agent scanning it. Some sentences are overloaded — the opening clause packs seven operations and the example-phrase sentence strings four quotes together — but essentially every sentence carries information that is not duplicated by 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?

This is a high-complexity dispatcher: 11 parameters, a nested book object, an enum of seven actions, and a destructive annotation with no output schema. The description handles the essentials — who may call it, which intents map to it, that notifications fire, and that the result reports a count — which covers the missing output schema. What it omits is per-action reversibility and what happens to a poll's existing votes when it closes, a modest gap rather than a blocking one.

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 already 91%, so the baseline is 3, but the description adds genuine interpretation: 'place is a place's name, never a street address' closes a likely failure mode that the schema's terse 'a place's name' leaves open, and the example phrasings clarify what 'text' should contain for post_pinned. It does not touch cross-field interactions (e.g. that 'choose' must be an option from the poll being closed), so it is above baseline but not exhaustive.

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 verb set and the resource scope: 'For a club's host or moderator: set or finish the book, open or close a poll, set or cancel the next meeting, or post a pinned message.' It enumerates the seven operations that map onto the 'do' enum, so an agent can match a user request to this tool without opening the schema, and the audience qualifier distinguishes it from member-facing siblings like respond_to_club or get_club.

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?

Usage is pinned down with concrete user-phrase triggers ('set up a vote between these three', 'we meet the 14th at Noor's', 'we finished it', 'ask the club this question'), plus an explicit exclusion: 'Removing members and closing a club are done in the app.' It also supplies a pre-call instruction ('Say what you're about to post before posting'), so the agent knows both when to reach for this tool and what to do immediately before invoking it.

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