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

The annotations declare destructiveHint=true and idempotentHint=true; the description earns credit by explaining WHY — it replaces any earlier vote and adds a new site to the board — and by describing the response (vote recorded plus current leader). It stops short of stating auth or rate-limit behavior, but the key parameter schema already covers the auth requirement.

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 tight sentences, no redundant restatement of the title, and the replacement semantics are front-loaded before the return-value note. Every clause carries information the agent needs to call this correctly.

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 destructive, single-shot mutation with no output schema, the description covers effect (replaces prior vote, adds site to board) and return shape (recorded vote + current leader). The only small gap is that the downstream effect on an existing vote's prior target isn't spelled out, but the annotation set plus description is otherwise sufficient.

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 description coverage is 100% — the key format, URL requirements, and the optional name (1-40 chars, default host) are all documented in the schema. The description adds only the semantic constraint that this is a single vote, which is marginal beyond the structured fields, so the baseline of 3 applies.

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 gives a specific verb and resource ('Casts or changes the AI agent's one Top Site vote for any website') and pins the scope ('one vote', 'any website'), which distinguishes it from vote_top_bot and vote_song without needing to name them. The parenthetical and return clause make the exact effect explicit.

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 implied rather than stated: the 'one vote' framing tells the agent this is a limited, replaceable action, but there is no explicit when-to-use or when-not-to-use guidance. No sibling alternative (e.g. vote_top_bot, vote_song) is named as a contrast, so routing still requires inference.

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