Enables interaction with Vercel AI Gateway for typed AI judgments, including step routing, tool selection, patch review, claim verification, and more.
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., "@vercel-jev-mcp Review this proposed patch and tell me whether to apply it."
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.
A local stdio MCP server that gives Cursor, Codex, and other MCP clients typed TypeSafe Jev judgments over the Vercel AI Gateway. Jev returns Choice, Score, and Noul answers; the host agent still edits files and runs commands.
One key, one endpoint, one bill: AI_GATEWAY_API_KEY and POST https://ai-gateway.vercel.sh/v1/evaluate with model typesafe-ai/jev.
Tool | Purpose |
| Route the next step and select a prepared call in one request |
| Route the next step and decide whether a partner model is needed |
| Select an exact host-prepared tool call without generating arguments |
| Assess a proposed patch |
| Check claims against supplied evidence |
| Combine patch review and claim verification in one upstream call |
| Screen untrusted content before the host reads it |
| Rank candidates supplied by the host |
| Ask custom, atomic typed questions |
Results include typed answers, token usage, and an action: auto, review, or escalate. Confidence measures model certainty, not factual truth. Incomplete context never permits auto; reduce the input and submit it again for a complete judgment.
Question packs are MCP resources at jev://packs/{coding-loop,tool-route,step,review,verify,screen,rank,gate}.
Related MCP server: MCP Gateway
The judgment engine, the question packs, and the typed policy layer are unchanged. What the gateway adds:
One credential and one bill. AI_GATEWAY_API_KEY replaces a provider-specific key; model choice, routing, and fallbacks are gateway configuration, and the same key serves every other model you already route there.
Real per-call accounting. Each response carries gateway marketCost, a generationId, and token usage. The eval CLI and doctor surface them, so a Jev swarm is measurable instead of estimated.
Deadline-aware retry. Transient gateway failures (408, 429, 5xx, connection drops) are retried with exponential backoff, honouring Retry-After, and never past the tool deadline — the same shared budget that already covers ranking rounds.
No vendor SDK. The transport is a typed fetch call against the documented wire contract; the internal domain model in src/jev-types.ts stays the single source of truth for what the tools see.
jev_step answers the whole loop turn in one request: it routes the step and, when the host supplies prepared calls, selects among them. A host that would otherwise call jev_coding_loop and then jev_tool_route spends one MCP round-trip instead of two, so it spends one host-model turn instead of two. Both original tools remain available.
Let host code execute known steps and prepare exact tool calls from an existing plan. When a semantic choice is needed, pass those calls to jev_step or jev_tool_route; either returns an executable call only for a confident, suitable selection with complete context and validated host facts. The host executes that call and routes again using the new observation. Jev never invents arguments or executes tools.
When a new plan or code may be needed, use jev_coding_loop with trusted execution facts. Its handoff distinguishes tool use, context gathering, review, user input, stopping, and a partner model. Invoke a generative partner only when partner_model.required is true; the legacy model_tier answer alone does not request a model turn. Uncertainty and escalation do not automatically spend a partner turn.
The prepared-call router accepts at most 32 candidates. Empty or wholly ineligible lists return locally with zero Jev usage. Other routing calls use Jev; this reduces unnecessary generative handoffs by policy, but live quality and cost savings have not been measured. See the tool contracts and host workflow.
Install Node 20+ and run from a checkout:
npm ci
npm run buildSet an AI Gateway API key in your shell, then run diagnostics:
export AI_GATEWAY_API_KEY=vck_...
node dist/index.js doctor
node dist/index.js doctor --jsonPowerShell:
$env:AI_GATEWAY_API_KEY = 'vck_...'
node dist/index.js doctor --jsonFor a deterministic local demo, set JEV_MCP_MOCK=1 instead. Mock mode is for tests and demos, not production decisions. Neither the CLI nor MCP automatically reads .env; see configuration for explicit environment-file use.
Cursor: copy the MCP example into .cursor/mcp.json, replace its argument with the absolute path to this checkout's dist/index.js, and set the key in env.
Codex: register the absolute path:
codex mcp add jev --env AI_GATEWAY_API_KEY=vck_... -- node /absolute/path/to/vercel-jev-mcp/dist/index.jsCopy the agent skill into the project so the host knows when to call these tools. Detailed setup is in installation.
node dist/index.js # stdio MCP
node dist/index.js doctor # human-readable diagnostics on stderr
node dist/index.js doctor --json # structured diagnostics on stdout
node dist/index.js eval --stdin < request.jsonAn evaluation request contains state and a questions map:
{
"state": "Production payouts are failing. Urgent.",
"questions": {
"urgent": { "type": "noul", "instructions": "Is this urgent?" }
}
}eval prints the typed answers plus usage and, on a live call, the gateway's provider block (cost_usd, generation_id):
{
"answers": { "urgent": { "type": "noul", "noul": 0.92 } },
"usage": { "input_tokens": 407, "output_tokens": 70 },
"provider": { "cost_usd": 0.000011592, "generation_id": "gen_01M2YEY6S02VMFPV8BMED0PX0G" }
}Diagnostics do not log request content or API keys. Calls have a 30-second total deadline by default, configurable with JEV_MCP_TIMEOUT_MS; transient gateway failures retry inside that deadline. API failures and invalid responses return typed errors rather than fabricated judgments.
State plus questions must fit the estimated 64,000-token total budget and the 32,000-token state-plus-longest-question budget. State may be shortened; results expose incomplete coverage and cannot automatically accept a judgment based on omitted context. Questions alone that exceed the budget are rejected. State is sent to the gateway as text, so a truncated evaluation truncates what Jev reads, not just what you see.
Rank accepts unique candidate IDs and at most 5,000 supplied candidates, with at most 250 options per upstream call. Larger lists use repeated reduction rounds; each candidate text is capped at 2,000 characters. Verify and gate accept at most 1,000 claims. A Score question takes 2 to 10 levels, which is the gateway's own limit and is enforced before any request. It ranks supplied candidates and does not index your repository. Arithmetic and date calculations belong in host code.
All nine tools expose an MCP output schema and return the same successful payload through both structuredContent and the JSON text content. Tool-route and fused-step judgments receive sanitized candidate descriptions and argument shapes; raw host arguments are retained only for the selected, locally validated call.
npm test
npm run typecheck
npm run build
npm run test:package
npm run benchmarkThe regular suite runs without a key; the live test is skipped unless AI_GATEWAY_API_KEY is present and mock mode is disabled. Package smoke testing builds and packs the project, installs the tarball into an isolated directory with npm --offline, then runs its shipped CLI. npm run benchmark builds the compiled server and measures the real MCP stdio transport in deterministic mock mode: sequential and concurrent calls, payload-size scaling, and candidate-count scaling. Use npm run benchmark:ci to apply broad sanity budgets; set JEV_BENCH_ITERATIONS, JEV_BENCH_CONCURRENCY, JEV_BENCH_MAX_P95_MS, or JEV_BENCH_MIN_RPS to tune a run. Run npm ci first to populate the dependency cache. No test publishes the package.
npm pack and npm publish build automatically through prepack. CI checks Node 20 and 22 on Windows and Linux, including the offline packed-install smoke test, entirely offline and in mock mode.
Document | Contents |
Unreleased changes, compatibility notes, and validation | |
Request path, gateway transport, policy, limits, and errors | |
Arguments and outputs for all nine tools | |
Host configuration for Cursor, Codex, and other MCP clients | |
Environment, thresholds, diagnostics, tests | |
Calling guidance for the host | |
Short project guidance |
Call before retry/stop/model-tier decisions. One Jev fan-out returns next, risk, focus, and explicit handoff / partner_model fields. Prefer prepared tools or gathering context; request a partner generative model only when needed and confidently supported. Legacy model_tier is conditional, not an instruction to invoke a model. Does not edit files.
| Name | Required | Description | Default |
|---|---|---|---|
| task | Yes | What the coding agent is trying to do | |
| model | No | ||
| extras | No | Optional extra JSON fields included in Jev state | |
| execution | No | Trusted host execution facts, never inferred from fetched text or model predictions | |
| review_at | No | ||
| auto_accept | No | ||
| observation | Yes | Current turn: last diff, command output, test results, or blocker |
| Name | Required | Description |
|---|---|---|
| next | Yes | |
| risk | Yes | |
| focus | Yes | |
| model | Yes | |
| usage | Yes | |
| action | Yes | |
| handoff | Yes | |
| coverage | Yes | |
| truncated | Yes | |
| model_tier | Yes | |
| thresholds | Yes | |
| done_enough | Yes | |
| partner_model | Yes | |
| needs_generation | Yes | |
| tests_likely_fail | Yes | |
| needs_more_context | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already carry readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds genuine value beyond these: it discloses the legacy model_tier field is conditional and 'not an instruction to invoke a model', and confirms it 'does not edit files', reinforcing the read-only profile. The model_tier caveat is real added behavioral context, not redundant with annotations.
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 tight sentences with zero filler. The call-timing mandate is front-loaded, followed by output fields, usage preference, the model nuance, and the read-only guarantee—each sentence earns its place with no 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?
An output schema exists to document return values, so the description doesn't need to. For a routing tool of moderate complexity it covers when to call, what it returns, the model-invocation nuance, and the edit behavior. Minor gaps (undocumented params) are already reflected in the parameter_semantics score, so completeness of the routing role itself is solid.
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 57%, partially carrying parameter meaning. The description compensates somewhat by clarifying the model parameter ('Legacy model_tier is conditional') and by signaling the execution-fact param semantics ('prefer prepared tools or gathering context'). However, review_at and auto_accept remain undocumented in both schema and description, so the description doesn't fully close the coverage gap.
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?
States a specific verb+resource ('Call before retry/stop/model-tier decisions' on the Jev coding-loop router) and enumerates what it returns (next, risk, focus, handoff/partner_model fields). The scoping to retry/stop/model-tier decisions gives useful distinguishing context versus its sibling jev_* tools, though it doesn't name an alternative explicitly.
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?
Explicitly positions when to call ('before retry/stop/model-tier decisions') and gives when-not guidance ('Prefer prepared tools or gathering context; request a partner generative model only when needed and confidently supported'). It lacks explicit named sibling alternatives, but the conditional model-request instruction is a clear prescriptive boundary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Escape hatch: send shared state plus named noul/choice/score questions to TypeSafe Jev. Use when no other jev_* recipe fits. Jev does not write code or prose. Questions in one call run in parallel. Returns typed answers, probabilities, confidence, usage, and action auto|review|escalate.
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | Override, default typesafe-ai/jev | |
| state | Yes | Shared state to judge: text or JSON | |
| questions | Yes | Named noul, choice, and score questions evaluated in parallel |
| Name | Required | Description |
|---|---|---|
| model | Yes | |
| usage | Yes | |
| action | Yes | |
| answers | Yes | |
| coverage | Yes | |
| truncated | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, open-world, idempotent, and non-destructive behavior. The description adds useful behavioral context beyond that: parallel execution of questions, the no-code/no-prose constraint, and the concrete return shape including action auto|review|escalate. No contradiction with annotations.
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?
Two compact sentences front-load the purpose and usage guidance. Every clause earns its place: escape-hatch role, selection criterion, capability boundary, execution model, and return summary. No redundant or filler language.
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 rich input schema, output schema, and annotations, the description is complete enough for an agent to decide and invoke correctly. It covers when to use the tool, what it cannot do, how questions behave, and what the caller gets back. No critical decision-making information is missing.
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 100%, so the schema already documents state, questions, and model. The description adds the notion of 'named' questions and parallel execution, but does not materially expand on parameter semantics beyond what the schema provides. Baseline 3 is appropriate.
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 a specific action—send shared state plus named noul/choice/score questions to TypeSafe Jev—and clearly frames it as an escape hatch. This distinguishes it from sibling jev_* tools by making clear it is the generic fallback when no more specific recipe applies.
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?
Provides explicit selection guidance: 'Use when no other jev_* recipe fits.' It also sets an exclusion boundary by stating Jev does not write code or prose, which helps the agent avoid misusing this tool for generation tasks better suited to other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Review a proposed patch and verify completion claims against supplied evidence in one Jev request. Returns review and verification reports, coverage, deterministic reason codes, and one overall auto|review|escalate action. Does not apply changes or execute tests.
| Name | Required | Description | Default |
|---|---|---|---|
| diff | Yes | Proposed patch, file excerpt, or change summary to review | |
| model | No | ||
| tests | No | Test output for the patch review | |
| claims | Yes | Completion claims to check against evidence; at most 1000 per request | |
| request | Yes | What the user asked for; this is not evidence of completion | |
| evidence | Yes | Sources that support the claims; include relevant diff or test logs here | |
| review_at | No | ||
| auto_accept | No |
| Name | Required | Description |
|---|---|---|
| model | Yes | |
| usage | Yes | |
| action | Yes | |
| review | Yes | |
| coverage | Yes | |
| truncated | Yes | |
| reason_codes | Yes | |
| verification | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as readOnly, idempotent, and non-destructive. The description adds useful behavioral context by confirming it does not apply changes or execute tests, and by disclosing the output shape: reports, coverage, deterministic reason codes, and an overall auto|review|escalate action.
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 sentences, front-loaded with the core purpose, followed by outputs and boundary conditions. Every sentence earns its place with no 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 an output schema and safety annotations, the description covers the main purpose, required evidence relationship, and non-mutating behavior. It is mostly complete, but it could benefit from explicit routing guidance versus jev_review/jev_verify and clarification of the threshold parameters.
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 63%, with good descriptions for request, diff, claims, evidence, and tests. The description reinforces the claims/evidence relationship but adds nothing about the poorly documented model, review_at, and auto_accept parameters, leaving their meaning and thresholds unclear.
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 uses a specific verb and resource: 'Review a proposed patch and verify completion claims against supplied evidence in one Jev request.' It clearly distinguishes itself from the sibling review/verify tools by being a combined gate, and it states what it returns plus what it does not do.
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 intended use is clear: use this tool when a proposed patch needs review and completion claims need verification against evidence. It also states an exclusion ('Does not apply changes or execute tests'). However, it never explicitly names jev_review/jev_verify as alternatives or states when they should be preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rank files, symbols, errors, or skills against a plain-language query. No embeddings. One Choice over candidate ids plus a Noul that the top hit actually answers the query (so a forced winner cannot masquerade as a match). Accepts up to 5,000 supplied candidates; each Jev call uses at most 250 options and larger lists are chunked then re-ranked. Pass candidates in; this server does not index the repo.
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | ||
| query | Yes | What you are looking for, in natural language | |
| top_k | No | How many ranked candidates to return. Default 5. | |
| candidates | Yes | Candidates with unique IDs. Large lists are ranked in batches that fit the context budget; at most 5000 candidates are accepted per request. |
| Name | Required | Description |
|---|---|---|
| top | Yes | |
| model | Yes | |
| usage | Yes | |
| action | Yes | |
| chunks | No | |
| exists | Yes | |
| winner | Yes | |
| chunked | Yes | |
| coverage | Yes | |
| truncated | Yes | |
| exists_verdict | Yes | |
| winner_confidence | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnly, openWorld, idempotent), the description discloses the Noul mechanism that verifies the top hit actually answers the query, the chunking behavior (each call uses at most 250 options, larger lists are chunked and re-ranked), and the 5,000-candidate limit. These are valuable behavioral traits not captured in annotations.
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 concise sentences with no fluff. It front-loads the primary purpose, then adds key behavioral details, and ends with a scope disclaimer. Every sentence earns its place.
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 an output schema exists, return values are covered. The description explains the core ranking behavior, the Noul check, chunking, candidate limits, and the server's non-indexing scope. This is sufficient for an agent to correctly invoke the tool.
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 75%; query, top_k, and candidates have descriptions. The description adds context about candidate limits and chunking but does not explain the 'model' parameter or further clarify top_k semantics beyond the schema. It adds some value but does not fully compensate for the missing model description.
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 the exact verb 'Rank' and the resource types ('files, symbols, errors, or skills') against a plain-language query. It also differentiates by noting 'No embeddings' and 'Pass candidates in; this server does not index the repo,' making its scope distinct from repo-indexing 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 gives clear context: it requires supplied candidates and does not index the repo, implying it should be used when candidates are already available. It does not explicitly name alternative tools or list when-not conditions beyond 'does not index the repo,' so it lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Score a proposed diff against the request: correctness, spec-match, test-gap, blast-radius, plus noul safe_to_apply. Composite weights live in code. Call before declaring a fix done. Does not apply the patch.
| Name | Required | Description | Default |
|---|---|---|---|
| diff | Yes | Proposed patch, file excerpt, or change summary | |
| model | No | ||
| tests | No | Test output if any | |
| request | Yes | What the user asked for | |
| review_at | No | ||
| auto_accept | No |
| Name | Required | Description |
|---|---|---|
| model | Yes | |
| usage | Yes | |
| action | Yes | |
| scores | Yes | |
| weights | Yes | |
| coverage | Yes | |
| composite | Yes | |
| truncated | Yes | |
| thresholds | Yes | |
| safe_to_apply | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds concrete behavioral detail beyond the annotations: the tool explicitly does not apply the patch, and 'Composite weights live in code' tells agents that scoring weights are internal and not configurable. No contradiction with annotations exists, though the phrase 'noul safe_to_apply' is confusingly typed.
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 compact and front-loaded, with no redundant filler. The incorrect 'noul' and the cryptic 'Composite weights live in code' sentence slightly reduce clarity, but the overall size and structure are appropriate.
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 core use case, timing, and non-application behavior are covered, and an output schema exists to explain return values. However, three parameters remain semantically ambiguous, so the description alone is not fully complete for all invocation options.
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 only 50%, and the description only reinforces the core request/diff semantics. It does not clarify model, review_at, or auto_accept, which also lack schema descriptions, so an agent cannot confidently understand their meaning or constraints.
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 uses a specific verb and resource ('Score a proposed diff against the request') and names concrete review criteria, so an agent can tell it is a review tool. It does not explicitly distinguish itself from the many sibling jev tools, though 'Does not apply the patch' helps separate it from patch-applying 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?
'Call before declaring a fix done' gives clear timing guidance, and 'Does not apply the patch' is a useful exclusion. It does not name alternatives like jev_verify or jev_evaluate, so when to choose this over a sibling is still partly left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Judge fetched or pasted text before the agent reads it: prompt-injection probability, substance, and optional relevance to purpose. Recommendation: pass|review|block|skip. Use on untrusted web pages, issues, and pastes. Not for first-party repo files.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Fetched or pasted text before the agent reads it | |
| model | No | ||
| purpose | No | What the agent is trying to do; enables relevance and skip | |
| block_at | No | ||
| review_at | No |
| Name | Required | Description |
|---|---|---|
| model | Yes | |
| usage | Yes | |
| action | Yes | |
| coverage | Yes | |
| truncated | Yes | |
| thresholds | Yes | |
| probabilities | Yes | |
| recommendation | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the tool is safe. The description adds behavioral context by specifying the judgment criteria (prompt-injection probability, substance, optional relevance) and the recommendation scale, which is consistent with annotations. No contradictions.
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 with no redundancy. The core action and output are front-loaded, followed by usage context and an exclusion. Every sentence earns its place.
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 tool has an output schema, so return values are covered there. The description covers purpose, usage, and exclusions. However, the threshold parameters (block_at, review_at) are unexplained, leaving an agent unclear on how to set them. This is a notable gap for a tool with 5 parameters and only 40% schema coverage.
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 only 40% (text and purpose have descriptions; model, block_at, and review_at do not). The description mentions 'optional relevance to purpose' which partially explains the purpose parameter, but it does not explain block_at and review_at thresholds or how they map to the recommendation values. With low coverage, the description should compensate, but it does not.
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 ('Judge'), a resource ('fetched or pasted text'), and the core output (prompt-injection probability, substance, optional relevance, and a recommendation scale). It clearly distinguishes from siblings by explicitly scoping to untrusted content and excluding first-party repo files.
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 explicitly states when to use ('Use on untrusted web pages, issues, and pastes') and when not to ('Not for first-party repo files'). It does not name a specific alternative tool for the excluded case, so it lacks the 'alternatives' component of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One call instead of jev_coding_loop then jev_tool_route: route the coding step and select among up to 32 host-prepared calls in a single Jev request. Returns the exact call with handoff execute_tool, or handoff use_tools|gather_context|partner_model|ask_user|stop|review with call null. Same dispatch floors. Never generates arguments, executes calls, or invokes a model.
| Name | Required | Description | Default |
|---|---|---|---|
| task | Yes | What the coding agent is trying to do | |
| model | No | ||
| extras | No | Optional extra JSON fields included in Jev state | |
| execution | No | Trusted host execution facts, never inferred from fetched text or model predictions | |
| review_at | No | ||
| candidates | No | Up to 32 host-prepared calls to choose from. Omit when none is prepared; ineligible candidates are filtered locally and never reach Jev. | |
| auto_accept | No | ||
| observation | Yes | Current turn: last diff, command output, test results, or blocker |
| Name | Required | Description |
|---|---|---|
| call | Yes | |
| next | Yes | |
| risk | Yes | |
| focus | Yes | |
| model | Yes | |
| usage | Yes | |
| action | Yes | |
| handoff | Yes | |
| coverage | Yes | |
| selection | Yes | |
| truncated | Yes | |
| model_tier | Yes | |
| thresholds | Yes | |
| done_enough | Yes | |
| reason_codes | Yes | |
| partner_model | Yes | |
| needs_generation | Yes | |
| tests_likely_fail | Yes | |
| blocked_candidates | Yes | |
| needs_more_context | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
It discloses important behavioral boundaries beyond the annotations: 'Never generates arguments, executes calls, or invokes a model' and enumerates exact handoff outcomes. This adds real value, though the phrase 'Same dispatch floors' is vague and not explained.
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 sentences, front-loaded with the key differentiator and a compact summary of behavior. It is tight and efficient, but 'Same dispatch floors' is compressed jargon that may confuse agents, preventing a perfect score.
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 covers purpose, sibling relationship, handoff behavior, and the critical non-execution guarantee. With an output schema and safety annotations present, this is mostly sufficient, but the undefined 'dispatch floors' and lack of guidance on choosing among handoff options leave minor gaps.
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 description adds little direct parameter semantics; it only alludes to host-prepared calls, which maps loosely to the candidates field. With 63% schema description coverage, the schema carries most of the meaning, so the description neither compensates nor meaningfully enriches the parameters.
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 routes the coding step and selects among up to 32 host-prepared calls in a single Jev request. It explicitly names the siblings it replaces — jev_coding_loop and jev_tool_route — making differentiation immediate.
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 clearly frames the tool as a fused replacement for 'jev_coding_loop then jev_tool_route', which tells the agent when this tool is the right choice. It does not, however, discuss exclusions or compare against other siblings like jev_gate or jev_review, leaving some selection context implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Choose among up to 32 exact host-prepared tool calls without generating arguments or invoking a partner model. Host supplies trusted authorization, schema validation, prerequisites, effect and retry counts. Only confident, suitable, complete, low-risk selections expose a call; otherwise call is null. Empty/ineligible lists return locally without Jev. This server never executes the selected call. Use jev_coding_loop if new generation may be necessary.
| Name | Required | Description | Default |
|---|---|---|---|
| task | Yes | ||
| model | No | ||
| review_at | No | ||
| candidates | Yes | Up to 32 host-prepared calls. Empty or ineligible lists need no Jev request. Filter larger lists first. | |
| auto_accept | No | ||
| observation | Yes |
| Name | Required | Description |
|---|---|---|
| call | Yes | |
| model | Yes | |
| usage | Yes | |
| action | Yes | |
| handoff | Yes | |
| coverage | Yes | |
| selection | Yes | |
| truncated | Yes | |
| thresholds | Yes | |
| reason_codes | Yes | |
| partner_model | Yes | |
| blocked_candidates | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavior beyond the readOnly/idempotent annotations by disclosing that the server never executes the selected call, that it returns null when no selection is confident, and that authorization and validation are trusted host responsibilities. These are operationally important traits not visible from the annotations.
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 five short sentences with the central purpose first and supporting safety/usage constraints after. Every sentence contributes a distinct fact: no generation, host responsibilities, null fallback, no execution, and the sibling alternative.
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 the core routing behavior, the description is complete and aligns with the rich candidate schema and annotations. However, it never explains the purpose of required top-level inputs such as task and observation or optional controls like review_at and auto_accept, so an agent has clear but incomplete guidance.
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 only 17%, and the prose does not compensate for the top-level parameters: task, observation, model, review_at, and auto_accept are left unexplained. The candidate-array semantics are covered, but the required task/observation fields and control parameters remain ambiguous.
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?
Description opens with a specific action 'Choose among up to 32 exact host-prepared tool calls' and explicitly excludes generating arguments or invoking a partner model. It closes by naming the sibling for generation, so the tool's identity is distinct from jev_coding_loop.
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 states the primary use case (selecting a confident, suitable, complete, low-risk prepared call) and a concrete exclusion/alternative: use jev_coding_loop when new generation may be necessary. It also tells the agent that empty/ineligible candidate lists should return locally without calling Jev, which is a clear when-not-to-invoke rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check each claim against provided evidence (PR description, agent brief, docs, diffs). Returns per claim: verified|contradicted|unsupported, probabilities, confidence, and auto vs review. Prefer this over asking a chat model to 'double-check'.
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | ||
| claims | Yes | Factual claims to check; at most 1000 per request | |
| evidence | Yes | Source text, or a list of {id, text} documents | |
| auto_accept | No |
| Name | Required | Description |
|---|---|---|
| model | Yes | |
| usage | Yes | |
| action | Yes | |
| results | Yes | |
| summary | Yes | |
| coverage | Yes | |
| truncated | Yes | |
| thresholds | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral detail beyond the annotations: it discloses the output format (verified|contradicted|unsupported, probabilities, confidence, auto vs review) and the nature of evidence. Annotations already cover read-only, open-world, idempotent, and non-destructive traits, so the description complements rather than repeats them. No contradictions found.
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, concise, and front-loaded with the core action. The first sentence covers purpose and outputs; the second provides a usage preference. Every sentence earns its place with no fluff.
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 verification tool with an output schema present, the description adequately covers the core behavior, evidence types, and return categories. It omits details on model selection and auto_accept, but these are parameter-level concerns that the schema partially addresses. Overall, an agent can call the tool correctly with the given information, though parameter semantics remain a gap.
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 only 50%, covering claims and evidence but not model or auto_accept. The description does not compensate for this gap—it mentions 'claims' and 'evidence' generically but provides no additional meaning for the model or auto_accept parameters. The agent must rely on the schema alone for those, which are undocumented, leaving ambiguity.
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 checks each claim against provided evidence, enumerates evidence types (PR description, agent brief, docs, diffs), and specifies output categories. It is specific and distinct from siblings, though it does not explicitly name sibling alternatives. The title and description together make the purpose unambiguous.
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 advises to prefer this tool over asking a chat model to 'double-check', giving a clear usage context. However, it does not reference any sibling tools or mention when not to use it, leaving some room for inference about alternatives within the same family.
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.0jev_coding_loopjev_evaluatejev_gatejev_rankjev_reviewjev_screenjev_stepjev_tool_routejev_verifyScored across 9 tools
The tools are largely distinct, but a few are deliberately composite or overlapping: jev_step is effectively jev_coding_loop plus jev_tool_route, and jev_gate bundles jev_review and jev_verify. An agent must read the long descriptions carefully to select the right orchestration recipe, so misselection is possible despite the clear use-case notes.
All tools share the consistent jev_ prefix and lowercase snake_case style, which makes the set feel predictable. However, the suffix pattern is mixed: verb-style names like jev_review, jev_verify, and jev_rank sit alongside noun-style names like jev_gate, jev_step, and jev_coding_loop, plus the compound noun jev_tool_route.
Nine tools is a well-scoped count for this kind of workflow server, and each tool maps to a recognizable phase: screening, ranking, evaluation, routing, stepping, review, verification, and final gating. None of the tools feel like filler, and the set is large enough to cover meaningful decisions without becoming unwieldy.
The toolset covers the full intended lifecycle for a decision/review server: untrusted text screening, candidate ranking, arbitrary typed evaluation, tool/step routing, next-action loop decisions, diff review, claim verification, and a combined final gate. The deliberate exclusion of file edits/execution is consistent with the stated purpose, and jev_evaluate acts as an escape hatch to prevent dead ends.
Zero-setup MCP gateway securely connecting AI to your tools with authentication and workflows
AI Reasoning Cache & Consensus Layer with 11 MCP tools via Streamable HTTP.
A paid remote MCP for AI SDK MCP gateway registry, built to return verdicts, receipts, usage logs, a
One MCP tool for verified AI-agent outcomes with success-only charging.