Upvote

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, covering safety and mutation traits. The description adds resource scope but doesn't elaborate on idempotent behavior or side effects, so it provides minimal extra transparency beyond annotations.

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 immediately state the action and resource constraints with no filler. Every word adds value and the structure is ideal for a simple tool.

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 two-parameter tool with simple semantics, the description, combined with annotations and the enum schema, is nearly complete. The absence of an output schema is acceptable since the outcome of an upvote is straightforward.

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?

The description adds meaning to the 'resource' parameter by listing the supported types and explicitly calling out unsupported ones. However, it provides no information about the 'id' parameter, and schema coverage is 0%, leaving that parameter reliant on inference.

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 uses a specific verb 'Upvote' and clearly enumerates the resource types (epic, user story, task, issue). It distinguishes from the sibling 'vote_remove' by the opposite action even without naming it.

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?

The description explicitly states which resources support voting and excludes milestones and wiki pages. It doesn't mention alternatives like 'vote_remove' for removing a vote, but the guidance is clear enough for selecting the tool.

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