Skip to main content
Glama

jev_rank

Read-only

Ranks files, line ranges, or supplied texts by how well each helps answer a query, using calibrated relevance scores to filter and order candidates.

Instructions

Rank files or texts by how well each helps answer a query: a relative Choice over the batch for order, Jev's calibrated yes/no per item for filtering. Pass glob or paths for anything you have not already read — do NOT read files to pass their text. The server reads and chunks them and returns only path:start_line-end_line + score, so a 300-file search costs almost no context either way. Pass candidates (id + text) only for text you already hold: search hits, retrieved passages, tool results. unit: chunk (default) ranks line ranges, file ranks whole files by their best chunk. Prefer file for 'where is X': a header comment can outrank the code it describes. Sensitive files (.env, keys, credentials), binaries and generated output are never read; they come back in skipped. Order comes from a Choice among the strongest candidates: trust the top 1-3 when choice_margin >= 0.10, the tail is by relevance. relevance is P(helps answer the query) and drives min_relevance; low any_relevant means look elsewhere. score_spread (top minus median relevance) below 0.15 means the absolute scores are flat; choice_margin says whether the top pick was clear.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "query": "<query>"
    },
    "name": "jev_rank"
  }
}

Input Schema

NameRequiredDescriptionDefault
globNoA glob for the server to expand and read, e.g. "src/**/*.ts". Supports * ** ? [abc] {a,b}.
unitNoFor paths/glob: `chunk` (default) ranks line ranges, `file` ranks whole files by their best chunk.
pathsNoFiles for the server to read, relative to the project root (absolute paths inside it are fine).
queryYesWhat you are trying to find out.
top_kNoHow many ranked results to return. Default 10.
candidatesNoText you already hold, 1 to 500. Use this only when you did not have to read a file to get it.
instructionsNoOptional extra definition of what counts as relevant here, folded into every question.
min_relevanceNoDrop candidates whose relevance is below this. Default 0 (keep everything).

Output Schema

NameRequiredDescriptionDefault
modelYesThe versioned model id that actually answered.
usageYesToken usage. Jev charges for input tokens only.
chunksYesHow many API requests this took: the fan-out over the batches plus the final deciding request.
rankedYesOrdered by the Choice among the strongest candidates, then by relevance for the tail. Text is never echoed back.
skippedNoFile sources only.
latency_msYesWall-clock time for the underlying API call(s), including retries.
any_relevantYesP(at least one candidate helps answer the query), judged once over the strongest candidates. Low means: look elsewhere.
est_cost_usdNoFile sources only: estimated input-token cost of this call.
score_spreadYesTop relevance minus median relevance, 2 decimals. How much the ranking actually discriminated. Below 0.15 the scores are effectively flat and the ordering is not informative: narrow the glob or rephrase the query rather than trusting the order.
choice_marginYesTop pick's Choice probability minus the runner-up's, in the request that decided the order, 2 decimals. Below 0.10 the top pick and the runner-up were a toss-up; open both.
chunks_scoredNoFile sources only: line-range chunks judged.
files_scannedNoFile sources only: files actually read.
total_candidatesYesHow many items were judged, before top_k/min_relevance.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed23 schema fields changedv0.7.0
    • changedInput schema / properties / candidates / description
      Previous value: -"The candidates to rank, 1 to 500."New value: +"Text you already hold, 1 to 500. Use this only when you did not have to read a file to get it."
    • addedInput schema / properties / glob
      Added value: +{
      +  "description": "A glob for the server to expand and read, e.g. \"src/**/*.ts\". Supports * ** ? [abc] {a,b}.",
      +  "minLength": 1,
      +  "type": "string"
      +}
    • addedInput schema / properties / paths
      Added value: +{
      +  "description": "Files for the server to read, relative to the project root (absolute paths inside it are fine).",
      +  "items": {
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "maxItems": 1000,
      +  "minItems": 1,
      +  "type": "array"
      +}
    • addedInput schema / properties / unit
      Added value: +{
      +  "description": "For paths/glob: `chunk` (default) ranks line ranges, `file` ranks whole files by their best chunk.",
      +  "enum": [
      +    "chunk",
      +    "file"
      +  ],
      +  "type": "string"
      +}
    • changedInput schema / required
      Previous value: -[
      -  "query",
      -  "candidates"
      -]New value: +[
      +  "query"
      +]
    • changedOutput schema / properties / any_relevant / description
      Previous value: -"P(at least one candidate helps answer the query), the maximum across chunks. Low means: look elsewhere."New value: +"P(at least one candidate helps answer the query), judged once over the strongest candidates. Low means: look elsewhere."
    • addedOutput schema / properties / choice_margin
      Added value: +{
      +  "description": "Top pick's Choice probability minus the runner-up's, in the request that decided the order, 2 decimals. Below 0.10 the top pick and the runner-up were a toss-up; open both.",
      +  "type": "number"
      +}
    • changedOutput schema / properties / chunks / description
      Previous value: -"How many API requests the candidate set was split into."New value: +"How many API requests this took: the fan-out over the batches plus the final deciding request."
    • addedOutput schema / properties / chunks_scored
      Added value: +{
      +  "description": "File sources only: line-range chunks judged.",
      +  "maximum": 9007199254740991,
      +  "minimum": -9007199254740991,
      +  "type": "integer"
      +}
    • addedOutput schema / properties / est_cost_usd
      Added value: +{
      +  "description": "File sources only: estimated input-token cost of this call.",
      +  "type": "number"
      +}
    • addedOutput schema / properties / files_scanned
      Added value: +{
      +  "description": "File sources only: files actually read.",
      +  "maximum": 9007199254740991,
      +  "minimum": -9007199254740991,
      +  "type": "integer"
      +}
    • changedOutput schema / properties / ranked / description
      Previous value: -"Sorted by relevance descending; ties keep input order. Candidate text is not echoed back."New value: +"Ordered by the Choice among the strongest candidates, then by relevance for the tail. Text is never echoed back."
    • addedOutput schema / properties / ranked / items / properties / choice
      Added value: +{
      +  "description": "The Choice probability from the request that placed this row (the final round for the top items, its own batch for the tail).",
      +  "type": "number"
      +}
    • addedOutput schema / properties / ranked / items / properties / end_line
      Added value: +{
      +  "description": "1-based, inclusive.",
      +  "maximum": 9007199254740991,
      +  "minimum": -9007199254740991,
      +  "type": "integer"
      +}
    • addedOutput schema / properties / ranked / items / properties / id / description
      Added value: +"Present for `candidates` sources: your own id, as passed."
    • addedOutput schema / properties / ranked / items / properties / path
      Added value: +{
      +  "description": "Present for file sources: path relative to the project root.",
      +  "type": "string"
      +}
    • changedOutput schema / properties / ranked / items / properties / relevance / description
      Previous value: -"P(this candidate helps answer the query), 0..1."New value: +"P(this item helps answer the query), 0..1. Absolute; what `min_relevance` filters on."
    • addedOutput schema / properties / ranked / items / properties / start_line
      Added value: +{
      +  "description": "1-based, inclusive.",
      +  "maximum": 9007199254740991,
      +  "minimum": -9007199254740991,
      +  "type": "integer"
      +}
    • changedOutput schema / properties / ranked / items / required
      Previous value: -[
      -  "id",
      -  "relevance",
      -  "rank"
      -]New value: +[
      +  "relevance",
      +  "rank",
      +  "choice"
      +]
    • addedOutput schema / properties / score_spread
      Added value: +{
      +  "description": "Top relevance minus median relevance, 2 decimals. How much the ranking actually discriminated. Below 0.15 the scores are effectively flat and the ordering is not informative: narrow the glob or rephrase the query rather than trusting the order.",
      +  "type": "number"
      +}
    • addedOutput schema / properties / skipped
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "File sources only.",
      +  "properties": {
      +    "binary": {
      +      "maximum": 9007199254740991,
      +      "minimum": -9007199254740991,
      +      "type": "integer"
      +    },
      +    "ignored": {
      +      "description": "Lockfiles, `*.min.*`, sourcemaps and ignored directories.",
      +      "maximum": 9007199254740991,
      +      "minimum": -9007199254740991,
      +      "type": "integer"
      +    },
      +    "not_found": {
      +      "maximum": 9007199254740991,
      +      "minimum": -9007199254740991,
      +      "type": "integer"
      +    },
      +    "outside_root": {
      +      "description": "Paths that resolved outside the project root, symlinks included.",
      +      "maximum": 9007199254740991,
      +      "minimum": -9007199254740991,
      +      "type": "integer"
      +    },
      +    "sensitive": {
      +      "description": "Files holding credentials. Never read, never sent, whatever named them.",
      +      "maximum": 9007199254740991,
      +      "minimum": -9007199254740991,
      +      "type": "integer"
      +    },
      +    "too_large": {
      +      "maximum": 9007199254740991,
      +      "minimum": -9007199254740991,
      +      "type": "integer"
      +    }
      +  },
      +  "required": [
      +    "binary",
      +    "too_large",
      +    "sensitive",
      +    "outside_root",
      +    "not_found",
      +    "ignored"
      +  ],
      +  "type": "object"
      +}
    • changedOutput schema / properties / total_candidates / description
      Previous value: -"How many candidates were judged, before top_k/min_relevance."New value: +"How many items were judged, before top_k/min_relevance."
    • changedOutput schema / required
      Previous value: -[
      -  "ranked",
      -  "any_relevant",
      -  "chunks",
      -  "total_candidates",
      -  "model",
      -  "usage",
      -  "latency_ms"
      -]New value: +[
      +  "ranked",
      +  "any_relevant",
      +  "choice_margin",
      +  "score_spread",
      +  "chunks",
      +  "total_candidates",
      +  "model",
      +  "usage",
      +  "latency_ms"
      +]
  2. First observedv0.1.4

TDQS

A4.3/5.0
Behavior5/5

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

Goes well beyond the readOnly/openWorld annotations: it states the server reads and chunks files itself, returns only `path:start_line-end_line` plus score so context cost is low, and that sensitive files, binaries and generated output are never read but returned in `skipped`. It also supplies interpretation thresholds (`choice_margin` >= 0.10, `score_spread` < 0.15) that tell the agent how to act on the output, which is exactly the non-obvious behavior an agent needs.

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

Conciseness4/5

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

Purpose is front-loaded in sentence one, then mode selection, then output interpretation — a logical order with no filler sentences. It is dense and a few clauses duplicate the schema (`unit` definition appears almost identically in both places), which keeps it just short of a 5.

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?

For an 8-parameter tool with an output schema, the description covers the input-mode decision, the server-side read behavior, the safety exclusions, and how to read the ranking signals — nothing critical for correct invocation is left unspecified. Return-field definitions are correctly left to the existing output schema.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, and the description adds real selection semantics beyond it: the glob-vs-candidates split based on whether a file read was already paid, and the advice to prefer `unit: file` for 'where is X'. Some parameter text (`unit`, `min_relevance`) merely restates the schema descriptions verbatim, so it is additive but partly redundant.

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

Purpose4/5

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

The first sentence gives a specific verb and dual resource (files or texts), plus the two scoring outputs (relative Choice for order, calibrated yes/no for filtering), which is far more than the name alone conveys. It does not explicitly distinguish itself from siblings like jev_pick or jev_evaluate, leaving that differentiation to inference.

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

Usage Guidelines4/5

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

Strong in-tool routing: use `glob`/`paths` for anything not already read, use `candidates` only for text already held, and prefer `file` for 'where is X'. It gives no guidance about when to choose this tool over the sibling jev_* tools, so the alternative-tool dimension is absent.

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