Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@voting-mcp aggregate these ranked ballots using Borda count"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Principled social-choice aggregation as MCP tools — with a benchmark that measures the accuracy lift over naive majority vote.
Almost every multi-agent system aggregates votes with Counter(votes).most_common(1), throwing
away preference order and confidence. voting-mcp ships the real rules (Borda, Copeland,
Condorcet, approval, STV, linear opinion pool) as callable MCP tools — each with its known
axiomatic behavior and explicit, documented tie-breaking — plus a reproducible benchmark that
aggregates a diverse ensemble of LLMs on a reasoning set and reports accuracy with bootstrap
confidence intervals.
The server is pure compute: stdio transport, no network, no file writes, no secrets — clean against the OWASP MCP Top 10 by construction.
# run the server directly (once published)
uvx voting-mcp
# or from source
git clone https://github.com/HrishiKabra/voting-mcp && cd voting-mcp
uv sync
uv run python -m voting_mcp.serverAdd it to an MCP client (e.g. Claude Desktop claude_desktop_config.json):
{
"mcpServers": {
"voting": { "command": "uvx", "args": ["voting-mcp"] }
}
}Related MCP server: AOCS-OmegaMCP
Every tool takes a profile ({candidates, ballots}) and returns a Result with the full
co-winner set (winners, so ties are never hidden), the single tie-broken winner (or null
when none exists), a ranking, per-candidate scores, and a note.
Tool | Ballots | Notes |
| rankings | positional; Condorcet-inconsistent, clone-sensitive |
| rankings | Condorcet-consistent pairwise (+1 win, +0.5 tie) |
| rankings | returns the pairwise winner or an explicit no-winner on a cycle |
| approval sets | most-approved wins |
| rankings | single-winner instant-runoff; clone-resistant |
| distributions | linear pool — preserves confidence, not an argmax vote |
| rankings | baseline (most first choices) |
| rankings | strict >50% or no winner |
| any | dispatch by a |
Tie-breaking is an explicit parameter (lexicographic default, none, or seeded random).
Aggregate an ensemble of 5 models (one OpenAI-compatible client via OpenRouter) on ARC-Challenge and compare each rule to the naive majority vote:
uv sync --extra bench
uv run python -m bench.fetch_arc --limit 200
# prints a cost estimate and STOPS; add --yes to actually call the API, --mock for a free dry run
uv run python -m bench.run_ensemble --dataset bench/datasets/arc_challenge.jsonl --limit 200 --yes
uv run python -m bench.compare --dataset bench/datasets/arc_challenge.jsonl --limit 200Every raw response is cached under bench/results/raw/; re-runs never re-call the API, so
aggregation tweaks are free.
5-model ensemble (gpt-4o-mini · gemini-2.5-flash-lite · deepseek-v3 · claude-haiku-4.5 ·
glm-4.7), n = 200, bootstrap 95% CI. Two datasets of different difficulty; full write-up and
both plots in RESULTS.md.
MMLU-Pro (hard, baseline 73.5%) — the informative case:
Rule | Accuracy | 95% CI | paired Δ vs majority | p |
opinion_pool | 0.755 | [0.695, 0.815] | +0.020 [−0.011, +0.052] | 0.225 |
majority_vote (baseline) | 0.735 | [0.679, 0.788] | — | — |
approval | 0.701 | [0.640, 0.757] | −0.035 [−0.063, −0.006] | 0.014 |
stv | 0.693 | [0.630, 0.750] | −0.043 [−0.072, −0.015] | 0.002 |
copeland | 0.647 | [0.580, 0.710] | −0.088 [−0.127, −0.052] | <0.001 |
condorcet | 0.620 | [0.550, 0.685] | −0.115 [−0.155, −0.079] | <0.001 |
majority (strict) | 0.590 | [0.520, 0.655] | −0.145 [−0.189, −0.105] | <0.001 |
borda | 0.472 | [0.405, 0.540] | −0.263 [−0.323, −0.206] | <0.001 |
Δ is tested with a paired bootstrap on the per-question accuracy difference (same questions, so shared difficulty cancels), not by eyeballing the independent CIs.
The finding (honest): the value isn't "fancy voting beats majority." It's that the
confidence-preserving rule (opinion_pool) wins when the crowd is uncertain (+2.0pp, the only
rule above baseline — suggestive but not significant at n=200, paired p=0.225), while forcing
the distributions into full rankings actively hurts, significantly — every ranking rule is
below baseline at paired p≤0.014, and borda collapses to 0.472 because with 10 options the
tail of the ranking is mostly noise. Aggregate the confidence; don't throw it away. On
ARC-Challenge (baseline 96.8%, near-ceiling) nothing separates — no rule differs
significantly. See RESULTS.md.
uv run pytest -q
uv run ruff check .
uv run mypy --strict src
# exercise the tools in the MCP Inspector:
npx @modelcontextprotocol/inspector uv run python -m voting_mcp.serverNote: if you keep this repo under an iCloud-synced folder (e.g.
~/Desktop), iCloud can spawn duplicate.pthfiles that intermittently break the editable install. Tests usepythonpath=src; run the server withPYTHONPATH=srcif an import fails, or move the repo off the synced folder.
The choice of rules here grows out of the author's work on voting-rule design: Optimizing Voting Rules for Social Welfare and Beyond (AAMAS). That line of work asks which aggregation rules maximize welfare given how voters actually express preferences; this project applies the same lens to LLM ensembles — where the benchmark's answer is that confidence-preserving aggregation (the linear opinion pool) is what pays off, and forcing cardinal beliefs into ordinal rankings destroys signal.
MIT
Apply any rule by name (enum rule) — a single dispatch entrypoint.
Equivalent to the per-rule tools. rule is one of: borda, copeland,
condorcet, approval, stv, opinion_pool, plurality, majority.
| Name | Required | Description | Default |
|---|---|---|---|
| rule | Yes | ||
| seed | No | ||
| profile | Yes | ||
| tie_break | No | lexicographic |
| Name | Required | Description |
|---|---|---|
| note | No | |
| rule | Yes | |
| scores | No | |
| winner | Yes | |
| ranking | No | |
| winners | Yes | |
| tie_break | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must carry full behavioral context. It only explains the dispatch nature, omitting details about side effects, auth requirements, or idempotency.
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 highly concise with two sentences, front-loading the core idea and listing the enum values efficiently.
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 4 parameters, no schema descriptions, and an output schema, the description fails to provide sufficient context about input structure, return values, or usage examples, making it incomplete for effective agent use.
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 description only explains the 'rule' parameter (listing its possible values). It does not describe 'profile', 'seed', or 'tie_break', leaving essential parameters 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?
The description clearly states the tool applies any rule by name using an enum, acting as a dispatch entrypoint. It distinguishes itself from sibling tools by noting equivalence to individual rule tools.
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 implies usage as an alternative to per-rule tools but does not provide explicit guidance on when to choose this tool over siblings or any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Approval voting: each candidate scores the total weight approving it.
Consumes approval ballots ({kind: "approval", approved: [...]}). An empty
approval set is valid and adds nothing. Errors if any ballot is not approval.
| Name | Required | Description | Default |
|---|---|---|---|
| seed | No | ||
| profile | Yes | ||
| tie_break | No | lexicographic |
| Name | Required | Description |
|---|---|---|
| note | No | |
| rule | Yes | |
| scores | No | |
| winner | Yes | |
| ranking | No | |
| winners | Yes | |
| tie_break | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description covers key behaviors: accepts approval ballots, treats empty approval set as valid, and errors on non-approval ballots. However, it does not mention tie-breaking behavior (despite a tie_break parameter) or the seed parameter's effect.
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 three sentences with no wasted words. It front-loads the core purpose, uses a code block for clarity on ballot format, and every sentence adds unique 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?
Given the tool's complexity (voting rule) and the existence of an output schema, the description covers the main input requirement but omits the optional parameters (seed, tie_break). It also fails to explain handling of ballot weights or tie-breaking scenarios, leaving gaps for a thorough understanding.
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%, so the description must compensate. It only hints at the profile parameter ('Consumes approval ballots') and neglects to explain the 'seed' and 'tie_break' parameters at all. The description adds minimal meaning beyond the schema's titles.
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 'Approval voting: each candidate scores the total weight approving it,' clearly specifying the voting rule and its mechanism. It distinguishes from other sibling tools by explicitly noting it only consumes approval ballots, contrasting with other rules.
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 states 'Consumes approval ballots... Errors if any ballot is not approval,' clearly indicating the tool is only appropriate when all ballots are approval type. It does not explicitly name alternatives, but the sibling tool names imply other rules for different ballot types.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Borda count over ranking ballots: positional scoring (top of m gets m-1).
Condorcet-inconsistent and clone-sensitive — useful as a contrast rule. Truncated ballots give unranked candidates the average of the remaining points (never a silent zero). Errors if any ballot is not a ranking.
| Name | Required | Description | Default |
|---|---|---|---|
| seed | No | ||
| profile | Yes | ||
| tie_break | No | lexicographic |
| Name | Required | Description |
|---|---|---|
| note | No | |
| rule | Yes | |
| scores | No | |
| winner | Yes | |
| ranking | No | |
| winners | Yes | |
| tie_break | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: scoring method, handling of truncated ballots (average of remaining points), and error condition if ballots are not rankings.
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?
Four concise sentences, each serving a distinct purpose: function definition, contrast role, truncated ballot handling, and error condition. No extraneous information.
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 the output schema exists (not shown), return values need not be explained. The description covers input constraints and key behaviors well, though it omits parameter details for seed and tie_break.
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 0%, so description provides critical context: only ranking ballots are valid, and scoring details. However, it does not explain the 'seed' or 'tie_break' parameters, which have defaults but 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?
The description clearly states it performs Borda count on ranking ballots, explains the scoring rule (top gets m-1), and distinguishes from siblings by noting it is Condorcet-inconsistent and clone-sensitive, useful as a contrast rule.
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?
Implicitly guides usage by specifying input must be ranking ballots only and noting its role as a contrast rule, but lacks an explicit statement of when to prefer Borda over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Condorcet winner over ranking ballots: beats every other candidate pairwise.
If the majority relation cycles (e.g. a>b>c>a) there is NO Condorcet winner:
winners is empty, winner is null, and note says so. Errors if any
ballot is not a ranking.
| Name | Required | Description | Default |
|---|---|---|---|
| seed | No | ||
| profile | Yes | ||
| tie_break | No | lexicographic |
| Name | Required | Description |
|---|---|---|
| note | No | |
| rule | Yes | |
| scores | No | |
| winner | Yes | |
| ranking | No | |
| winners | Yes | |
| tie_break | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the burden. It discloses error conditions (non-ranking ballots) and behavior in cycles (empty winners, null winner, note). This is sufficient behavioral context.
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 two sentences, front-loaded with the core purpose, no extraneous content. Every sentence adds 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?
Given the complexity (Condorcet rule, cycles, error handling) and the presence of an output schema, the description covers the main points but lacks parameter explanations. It is adequate but not exhaustive.
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?
With 0% schema description coverage, the description should explain all parameters. It only mentions that ballots must be rankings, but does not describe 'tie_break' or 'seed', leaving those unexplained.
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 computes the Condorcet winner from ranking ballots, with a specific verb and resource. It distinguishes itself from siblings like plurality or approval by specifying the voting method.
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 does not explicitly state when to use this tool over alternatives. It implies it only works with ranking ballots, but no direct comparison with sibling tools is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Copeland over ranking ballots: +1 per pairwise win, +0.5 per pairwise tie.
Condorcet-consistent: a candidate that beats all others pairwise wins. Errors if any ballot is not a ranking.
| Name | Required | Description | Default |
|---|---|---|---|
| seed | No | ||
| profile | Yes | ||
| tie_break | No | lexicographic |
| Name | Required | Description |
|---|---|---|
| note | No | |
| rule | Yes | |
| scores | No | |
| winner | Yes | |
| ranking | No | |
| winners | Yes | |
| tie_break | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses the core algorithm and that it errors on non-ranking ballots. However, it does not describe tie-breaking behavior, output format, or other edge cases.
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 three short sentences, front-loading the algorithm and key property, with no redundant information.
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 the complexity of a voting rule tool with multiple parameters and an output schema, the description lacks details on return values, tie-breaking, and the seed parameter, leaving gaps for the agent.
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%, so the description must compensate. It only indirectly references the 'profile' parameter by mentioning ranking ballots, but ignores 'tie_break' and 'seed' entirely.
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 computes Copeland scores from pairwise wins/ties and is Condorcet-consistent. It does not explicitly differentiate from sibling tools like 'condorcet', but the unique scoring mechanism is implied.
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 mentions Condorcet-consistent and that it only works with ranking ballots, but does not explicitly specify when to use this over alternatives like 'condorcet' or 'borda'. The error condition for non-ranking ballots provides some guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Strict-majority rule over ranking ballots.
A candidate wins only with > 50% of first-choice weight; otherwise there is
NO winner (winners empty, note explains). Distinct from plurality.
| Name | Required | Description | Default |
|---|---|---|---|
| seed | No | ||
| profile | Yes | ||
| tie_break | No | lexicographic |
| Name | Required | Description |
|---|---|---|
| note | No | |
| rule | Yes | |
| scores | No | |
| winner | Yes | |
| ranking | No | |
| winners | Yes | |
| tie_break | No |
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.
Linear opinion pool over probability-distribution ballots.
Returns the weight-averaged distribution in scores (it PRESERVES
confidence rather than collapsing to an argmax vote); winner is the
argmax for convenience. Ballots are {kind: "distribution", distribution: {cand: p, ...}} summing to 1. Errors if any ballot is not a distribution.
| Name | Required | Description | Default |
|---|---|---|---|
| seed | No | ||
| profile | Yes | ||
| tie_break | No | lexicographic |
| Name | Required | Description |
|---|---|---|
| note | No | |
| rule | Yes | |
| scores | No | |
| winner | Yes | |
| ranking | No | |
| winners | Yes | |
| tie_break | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that confidence is preserved, returns scores and winner, and enforces distribution constraints. However, it does not detail behavior for weighted ballots, tie-breaking, or seed parameter effects.
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 concise with three sentences, front-loading the core purpose and key constraints. Every sentence adds essential information without redundancy.
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 the tool's complexity (3 parameters, nested types) and that it has an output schema, the description covers the main operation and ballot constraint but omits important context about seed, tie_break, and weight support, leaving some gaps for an agent.
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 0% and the description only partially compensates by explaining the profile's ballot structure. Parameters like seed and tie_break are not described, leaving the agent to rely on the schema's $defs which are not explicitly tied to the tool's usage.
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 performs a linear opinion pool over probability-distribution ballots, specifies the output format (scores and winner), and distinguishes it from sibling tools by requiring distribution ballots only.
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 implicitly guides usage by emphasizing that ballots must be distribution ballots (summing to 1) and will error otherwise. This helps differentiate from sibling tools that handle other ballot types, but it does not explicitly state when not to use or mention alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Plurality baseline over ranking ballots: most first-choice votes wins.
| Name | Required | Description | Default |
|---|---|---|---|
| seed | No | ||
| profile | Yes | ||
| tie_break | No | lexicographic |
| Name | Required | Description |
|---|---|---|
| note | No | |
| rule | Yes | |
| scores | No | |
| winner | Yes | |
| ranking | No | |
| winners | Yes | |
| tie_break | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains the core behavior (counting first-choice votes) but does not disclose tie-breaking behavior despite the tie_break parameter. No annotations exist, so description carries full burden; it partially reveals outcomes but omits edge cases.
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?
Single sentence, front-loaded with key information. No redundancy; however, it could be expanded slightly to cover more details without losing conciseness.
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?
Despite a complex input schema with multiple ballot types and a tie_break parameter, the description provides minimal guidance. It assumes agents know plurality only uses first choices from ranking ballots, and does not address other ballot types or edge cases. With an output schema present, completeness is acceptable for basic use but insufficient for nuanced cases.
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%, so description must compensate. It only relates to the 'profile' parameter by mentioning ranking ballots, but ignores 'seed' and 'tie_break' entirely. This leaves important parameters 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?
The description clearly states the tool computes plurality baseline using ranking ballots, with a specific rule: most first-choice votes wins. This distinguishes it from sibling tools like approval or borda by specifying the ballot type and voting method.
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 implies when to use (plurality voting) but provides no explicit guidance on when to choose this tool over alternatives like approval or borda. No exclusions or alternatives mentioned, which limits its helpfulness for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Single-winner STV / instant-runoff over ranking ballots.
Rounds: count top active preferences; a strict majority wins, else eliminate the fewest-voted (ties broken by eliminating the lexicographically largest) and transfer. Ballots with no remaining preference are exhausted. Clone-resistant. Errors if any ballot is not a ranking.
| Name | Required | Description | Default |
|---|---|---|---|
| seed | No | ||
| profile | Yes | ||
| tie_break | No | lexicographic |
| Name | Required | Description |
|---|---|---|
| note | No | |
| rule | Yes | |
| scores | No | |
| winner | Yes | |
| ranking | No | |
| winners | Yes | |
| tie_break | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It details the iterative process: rounds, counting top preferences, strict majority win, elimination of fewest-voted with lexicographic tie-breaking, transfer of ballots, and exhaustion. It also mentions clone-resistance. This is thorough, though it could elaborate on edge cases like all candidates tied or handling of exhausted ballots.
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 concise, using three short paragraphs that front-load the purpose and then succinctly explain the algorithm. Every sentence earns its place; no filler or redundancy. It is well-structured for quick consumption.
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 the complexity of STV and the presence of an output schema, the description adequately covers the algorithm, constraints, and tie-breaking behavior. It does not mention the return format, but that is unnecessary due to output schema availability. It could be improved by noting that only ranking ballots are accepted, but that is already stated.
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 3 parameters (profile, tie_break, seed) but the description adds no information about them beyond what is in the schema. The description does not explain the effect of tie_break or seed, nor clarify that profile must contain ranking ballots. Schema description coverage is 0%, so the description fails to compensate.
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 it is for 'Single-winner STV / instant-runoff over ranking ballots.' This explicitly identifies the specific voting rule and ballot type, distinguishing it from sibling tools like plurality, approval, borda, etc. The verb 'compute' is implied, but the purpose is unmistakable.
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 implies usage when a single winner is desired from ranking ballots via STV/IRV. It states 'Errors if any ballot is not a ranking,' indicating a constraint. However, it does not explicitly state when to use this tool versus alternatives (e.g., for multi-winner contexts or when ballots are not rankings), providing only implicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.3aggregate_ruleapprovalbordacondorcetcopelandmajorityopinion_poolpluralitystvScored across 9 tools
Most tools are distinct voting methods with clear descriptions. However, `aggregate_rule` duplicates the functionality of the per-rule tools, potentially causing confusion about which to use.
Names are all lowercase and based on voting methods, which is consistent. However, the pattern is not uniform: some are single words (e.g., `borda`) while others use underscores (e.g., `opinion_pool`), and `aggregate_rule` breaks the naming convention of referring to a specific rule.
With 9 tools covering a variety of common voting rules plus a dispatch tool, the count is well-scoped for a voting MCP server. It is neither too sparse nor overly numerous.
The set includes major voting methods but lacks utility tools for managing ballots or providing rule descriptions. As a stateless tallying server, it covers core rules well but could be more complete with additional supporting tools.
Benchmark MCP tool selection with metadata-only routing, collision, abstention, and holdout checks.
Papers With Code MCP — browse ML research papers and their code repositories
MCP-native AI evaluation: rubric audits, eval suites, and proof reports for AI/LLM output.
Vouch — independently measured reliability scores for MCP tools, not self-reported claims.
