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

Annotations only declare read-only/non-destructive; the description adds substantial behavioral context the annotations cannot: votes are E2E-encrypted so counts are indicative, votes can be silently dropped when the device was unlinked, the response carries a completeness_caveat field, and group polls include a participant-count denominator. The explicit instruction never to report results as final is exactly the kind of operational caveat that prevents misuse.

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 purpose and modes, then the critical caveat — efficient ordering with no filler. The final sentence partially restates the caveat already implied by the completeness_caveat mention, a small redundancy, but it converts the caveat into an actionable instruction.

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?

An output schema exists, yet the description still flags the key response fields an agent must interpret (completeness_caveat, group participant denominator) and warns how to present them. Combined with the mode explanation and ID provenance, an agent has everything needed to call and correctly report this tool's output.

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 would be 3, but the description adds real semantics beyond the schema: the presence/absence of poll_id selects two distinct modes (single-poll retrieval vs. listing), and chat_id's provenance is stated. Limit and account are left to their schema descriptions, which already handle them adequately.

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?

Specific verb+resource ('Reads WhatsApp poll results') with the two operating modes spelled out: with poll_id returns question/options/vote counts, without it lists recent polls in the chat. An agent can immediately distinguish this from whatsapp_read_messages, whatsapp_send_poll, and other WhatsApp siblings.

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?

Gives an explicit precondition (chat_id MUST come from whatsapp_list_chats / whatsapp_list_groups) and a clear conditional for switching behavior via poll_id presence. It does not name an alternative tool for cases where a poll cannot be read or where message-level context is needed, so it stops short of a full when/when-not comparison.

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