cast_vote

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

Annotations already indicate destructiveHint=true (state change). The description adds that you can add more votes to a previously voted proposal, implying non-idempotent behavior. It does not disclose error conditions (e.g., insufficient votes), permissions, or rate limits. The description adds moderate context 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?

The description is very concise: three sentences that front-load the purpose. Every sentence provides essential information: what it does, prerequisites, parameter semantics, and repeatability. No wasted words.

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?

Given no output schema and full schema coverage, the description covers the action, prerequisites, and parameter details. It mentions that you can add more votes, which is important. It doesn't specify return values or error handling, but for a simple vote action, it is fairly complete.

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 descriptions cover 100% of parameters. The description adds that votes can be added to an existing vote, which provides extra behavioral context for the 'votes' parameter. However, it largely duplicates the schema for 'support' and doesn't add new detail for 'proposalId' or 'network'. Minimal additional value over schema.

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 clearly states the tool's purpose: 'Cast a vote on a governance proposal.' It specifies the meaning of the 'support' parameter (FOR/AGAINST) and notes the prerequisite of having available votes. This distinguishes it from sibling tools like 'get_user_vote_status' or 'deposit_jst_for_votes'.

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 includes important usage context: you must have available votes (deposit JST first if needed) and you can add more votes to a proposal already voted on. However, it does not explicitly state when to use this tool versus siblings like 'withdraw_votes_from_proposal' or 'check_jst_allowance_for_voting', nor does it provide alternatives or exclusions.

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