jev-agent-mcp

Rank candidates on weighted dimensions

rank_candidates

Read-only

Grade each candidate on several weighted dimensions to get a numeric ranking. Use when a choice depends on multiple factors such as relevance, risk, and effort.

Instructions

Rank 2-30 candidates (search results, candidate plans, next actions, models to route to) by grading each one on several described dimensions and combining the grades with your weights. Returns numbers only, never prose.

WHEN TO USE: you have a shortlist and the better choice depends on more than one factor (relevance and freshness; expected benefit, risk, and effort). For picking one option on a single question, use judge with a choice question instead.

WHAT TO PASS: "context" holds what every candidate is judged against (the query, the goal, constraints). Each candidate is graded in its own request, seeing only "context" and its own "content" as candidate, so grades are comparable and a candidate is never judged relative to the others. Dimensions must be independent; split "good and cheap" into two dimensions.

HOW TO READ THE RESULT:

"ranking" is sorted best first. "composite" is the weighted mean of the normalized dimension scores, from 0 to 1.
Each dimension reports "score" (probability-weighted level, can fall between levels), "normalized" (score divided by the top level), "confidence", and "certainty". The raw scores are returned so you can re-weight without calling again.
"top_margin" is the composite gap between first and second place. "top_tied" is true when that gap is at or below "tie_margin": the ranking does not separate the two, so do not trust their order. Break the tie on something else or treat both as equal.
Read the winner's "composite" as well as its rank. When every candidate is weak, the top one still has a low composite, and the right move may be to look for better candidates.
"needs_escalation" lists each candidate/dimension pair graded with low certainty. That usually means the candidate's content does not say enough about that dimension, or the levels overlap. If a flagged pair involves a top candidate, get the missing information or verify before acting on the ranking.

Input Schema

TableJSON Schema

Name	Required	Description
`context`	Yes	Named fields shared by every candidate: the query or goal, constraints, relevant facts.
`candidates`	Yes
`dimensions`	Yes
`thresholds`	No	Override the uncertainty thresholds for this call. Tighten them (e.g. confidence_high 0.9, noul_band [0.1, 0.9]) when acting on a wrong answer would be costly or irreversible.
`tie_margin`	No	First and second place count as tied when their composite gap is at or below this. Default 0.05.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`model`	Yes
`usage`	Yes
`ranking`	Yes
`top_tied`	Yes
`top_margin`	Yes
`needs_escalation`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 21, 2026

TDQS

A5/5.0

Behavior5/5

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

Annotations already declare readOnlyHint and openWorldHint, and the description adds meaningful behavioral context: each candidate is judged in its own request seeing only 'context' and its own 'content', candidates are never compared against each other, and low-certainty pairs are surfaced via 'needs_escalation'. It also explains how ties are handled and warns not to trust the order when 'top_tied' is true.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but tightly organized with clear sections (WHEN TO USE, WHAT TO PASS, HOW TO READ THE RESULT) and front-loads the core instruction. Each section earns its place by addressing a distinct decision the agent must make: when to call, what to pass, and how to interpret the response.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite the rich output schema, the description adds essential interpretation details: how to read 'composite', 'top_margin', 'top_tied', and 'needs_escalation', plus a warning about weak candidates where the top one still has a low composite. For a complex tool with nested parameters and multiple siblings, nothing needed for correct invocation or result interpretation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 60%, so the description needs to add meaning, and it does. It clarifies that 'context' is the shared basis for judging all candidates, that each candidate's 'content' is judged only against that context, that dimensions must be independent ('split good and cheap into two dimensions'), and that levels are ordered worst to best with cost-like dimensions having the most expensive case first.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Rank 2-30 candidates... by grading each one on several described dimensions'. It also states the output contract ('Returns numbers only, never prose') and explicitly distinguishes itself from judge, making the tool's purpose and scope immediately clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'WHEN TO USE' section states the exact condition for selection ('you have a shortlist and the better choice depends on more than one factor') and names the alternative for the opposite case: 'For picking one option on a single question, use judge with a choice question instead.' This is explicit when-to-use and when-not-to-use guidance.

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

Deploy Server