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

The description adds substantial context beyond the annotations: the vote's business effect, the email notification on status change, the duplicate-redirect rule, and the return payload. However, it explicitly claims "Idempotent: one vote per account" while the annotations declare idempotentHint=false, giving the agent a misleading picture of what a repeated call does.

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 key behavior (duplicate redirect, one vote per account, return value) is front-loaded, but the auth prerequisite is stated twice — "Free; needs a key" and then "Needs an API key or a connected account" — which is wasted text in an otherwise compact description.

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 single-parameter mutation with no output schema, the description covers side effects (vote counted, email on status change), auth requirements, and the return value. The only real gap is the conflicting idempotency claim that leaves repeated-call behavior ambiguous.

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% and the schema already explains that id comes from list_feedback, request_feature or report_issue. The description adds nothing about the id parameter, so the baseline 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?

States a specific verb and resource ("Adds your upvote to a feature request or issue") and explains the effect ("votes decide what gets built and fixed first"). It does not explicitly name the natural sibling remove_feedback_vote, so an agent must infer the inverse operation from the sibling list.

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 clear context for when to call it ("a 'me too'", duplicate votes are redirected to the original) and states cost/auth prerequisites. It stops short of stating when NOT to use it, e.g. to un-vote, which would require pointing at remove_feedback_vote.

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