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

There are no annotations, so the description carries full behavioral disclosure. It does well to state the arithmetic is deterministic, matching plainballot.com, and that issues with no sourced position are dropped rather than guessed; that 'never guessed' rule is genuinely useful. It stops short of saying what the response looks like when every issue is unscored, or whether the computation costs a lookup on the address.

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?

Three tight sentences, front-loaded with the scoring semantics and the 0-100 range, then the arithmetic provenance, then the input constraint. Nothing is redundant and no sentence is filler.

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 read-only scoring tool with no annotations and no output schema, the description covers the output scale, the missing-data policy, and the input-fabrication constraint, which is most of what an agent needs. The main remaining gap is the identity and format of the address parameter, which neither the schema nor the description explains.

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 effectively 0% at the top level: 'address' has no description at all, so the agent must guess whether it is the voter's residential address or a ballot identifier. The nested priorities object is well structured by the schema, including the issue enum and the side label that refers to list_issues, and the description adds the meaningful constraint that only user-supplied priorities may be passed. That helps, but the unexplained address keeps it at baseline.

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 states a specific verb and resource: it scores each choice on the voter's ballot against the voter's stated priorities, and it names the 0-100 output range. It is clearly distinct from get_ballot and list_issues, though it never names those siblings or explicitly separates itself from them.

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?

"Only use priorities the voter actually gave you" is a useful constraint that implies the tool applies when real voter priorities exist. However, it never tells the agent when to choose this tool over get_ballot or list_issues, and there are no stated prerequisites or exclusions beyond that one constraint.

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