majority

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

The description discloses that no winner occurs if no candidate exceeds 50% first-choice weight, and that 'winners' is empty with a 'note' explanation. However, it does not address tie-breaking behavior (though a tie_break parameter exists) or handling of non-ranking ballots, which the schema allows. Given no annotations, the description provides basic behavioral context but is incomplete.

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 extremely concise at two sentences, stating the core rule and a key distinction. It is front-loaded with the primary purpose and avoids unnecessary words. Every sentence contributes value.

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?

The description mentions the no-winner case and a 'note' explanation, but it omits important details like tie-breaking behavior (despite the tie_break parameter) and the fact that the profile can accept ballot types beyond rankings (approval, score, distribution), which the schema shows. The tool's output schema is noted as present, so return values are partly covered, but the description's scope is too narrow for the tool's complexity.

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 input schema has 0% description coverage for top-level parameters (profile, tie_break, seed), and the description does not add any meaning to these parameters. It mentions 'ranking ballots' but does not explain the profile parameter or the tie_break/seed options. The description fails to compensate for the lack of schema descriptions.

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 implements a strict-majority rule for ranking ballots, defines the win condition (>50% first-choice weight), and explicitly distinguishes it from plurality, a sibling tool. This provides a specific verb+resource and differentiation.

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?

While it mentions being distinct from plurality, it does not provide explicit guidance on when to use majority over other sibling tools like approval, borda, or condorcet. There is no 'when-to-use' or 'when-not-to-use' advice.

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