Plain Ballot

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

With no annotations supplied, the description carries the full behavioral burden. It does disclose the shape and provenance of the response (issue positions, verbatim quotes, source URLs), which is genuinely useful, but it omits coverage caveats such as what happens when a race has no research, whether results are cached, or any access requirements. The qualifier 'researched race' hints at partial coverage without explaining it.

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?

A single front-loaded sentence that leads with the resource and follows with what each result contains; no filler or meta-commentary. The trailing enumeration of result fields is slightly long but each element (position, quote, source) is substantive.

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 one-parameter read tool with no output schema, explaining the return payload is the most important thing the description can do, and it does so. Remaining gaps (empty/partial coverage behavior, relation to sibling tools) are modest given the tool's simplicity.

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 coverage is 100% and the single parameter is fully documented in the schema, so the baseline is 3. The description does add one useful constraint by scoping it to a 'U.S. street address', implying non-U.S. addresses are out of scope, which is not stated in the 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 names the resource precisely: the set of researched races on the ballot for a U.S. street address, plus what each entry contains (issue positions, exact quote, source URL). An agent can immediately tell this is an address-to-ballot lookup. It stops short of differentiating itself from siblings list_issues and score_fit, which it never mentions.

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?

There is no explicit when-to-use or when-not-to-use guidance, and neither sibling (list_issues, score_fit) is referenced, even though an agent could plausibly confuse this with score_fit for evaluation tasks. Usage is only inferable from the required address parameter and the word 'ballot'.

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

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

With no annotations and no output schema, the description carries the full disclosure burden and does real work: it reveals the exact count (18), that each issue has two sides, that wording is deliberately partisan per side, and that sides carry short labels. What it omits is the concrete return structure (field names, how sides are nested), which would matter for parsing.

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 short sentences with no filler; the subject of the tool is front-loaded. The sentence about partisan wording earns its place by warning the agent how to read the content, though the phrasing 'the way its own supporters would say it' is slightly wordier than needed.

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 parameterless list tool with no output schema, the description supplies the essential shape of the data: cardinality, the two-sided structure, and the label vocabulary. Only the precise response schema is left unspecified, which is a minor gap given how simple the call is.

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 tool takes zero parameters, so the baseline is 4 and there is nothing to disambiguate. The mention of 'l' and 'r' describes output labels consumed by score_fit rather than input parameters, so it adds context without creating parameter confusion.

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 resource — the 18 issues tracked by Plain Ballot — so an agent knows this is the enumeration tool rather than get_ballot or score_fit. It stops just short of an explicit verb like 'returns' or 'lists', relying on the title to supply it, and it never contrasts itself with get_ballot.

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?

It tells the agent to use the short side labels when supplying priorities to score_fit, which implies a call-first relationship with that sibling, but that is guidance about downstream data use rather than an explicit 'call this before score_fit' instruction. No exclusions or alternate paths are stated.

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

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.