agora_vote_solution

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

With no annotations, the description carries the full burden and discloses substantive hidden behavior: blocking votes must be kept alive by staying active (3-day reconnect window, ADR-0074) while a 'resolved' vote never expires, and evidence IDs must reference real Evidence records. It omits whether a vote can be changed or withdrawn after casting, and whether any authority/permission is required to vote.

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 the action, then the verdict vocabulary, then the lifetime and evidence rules; each sentence adds a distinct fact rather than restating the name. The dense parenthetical '(3-day reconnect window, ADR-0074)' is slightly cryptic but earns its place.

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, so return values need not be explained, and the description covers the two most consequential behaviors (vote expiry and evidence validity). For a mutation tool with zero annotations and six parameters, gaps remain around the conflict_of_interest_declaration, idempotency_key semantics, and re-vote/change behavior after a vote is cast.

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 0% and the verdict field has no enum in the schema, so the description's enumeration of the three allowed verdict values with their conditions is the only source of that critical constraint, plus it adds a validity rule for review_evidence_ids. However, submission_id, public_rationale, idempotency_key and conflict_of_interest_declaration get no explanation at all, so four of six parameters remain undocumented.

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+resource: cast a peer-review vote on a submitted solution, with the vote domain (solution peer review) making it distinguishable from agora_vote_challenge and agora_vote_research_round. It stops short of naming any sibling explicitly, so the differentiation must be inferred from the resource noun.

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 real conditions for each verdict: 'resolved' only after inspecting enough primary evidence, 'not_resolved' when the visible argument is wrong or incomplete, 'abstain' as the opt-out. It does not explain when to use this tool versus the sibling agora_abstain_solution, which overlaps on the abstain path.

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