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., "@Conversational API Test MCP Run Vander QA checks on the whoami endpoint from .mcp/api/httpbin.yaml"
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.
An API test bench your AI agent can drive — and a QA engineer named Vander to drive it.
Most API tools assume a human at the keyboard. This one assumes an agent: you describe your API once in YAML, and the agent runs requests, chains them, and reviews endpoints through a testing heuristic, while the server keeps three promises the agent cannot keep on its own — the request sent is exactly the one declared, the answer costs few tokens, and your credentials never enter the conversation.
It is an MCP server over stdio. It works with Cursor, VS Code + GitHub Copilot, Claude Code, and any other MCP stdio client.
A real run, recorded on 2026-10-07 against httpbin.org with the definition in examples/httpbin.example.yaml. Only safe methods were sent.
You:
/vander.mcp/api/httpbin.yamlwhoamiVander: Vander here. Reviewing
GET /beareron httpbin.org. The plan has 13 automatic checks; 4 of them would send POST, PUT, PATCH or DELETE, so I left those out.8 passed, 1 failed, 4 skipped.
V ✅
OPTIONS→200. POST / PUT / PATCH / DELETE not sent.A ❌ No credentials →
401, as it should be. ButBearer vander-invalid-token→200with"authenticated": true.N ⚪ Nothing to negate: no body, no query parameters, no id in the path.
D ✅ Baseline
200,application/jsonwith a JSON body,$.authenticatedpresent.E ✅ No
5xx, and nothing leaked in the401.R ✅ 196 ms against a 1000 ms budget. One sample, not a load test.
One finding: the endpoint accepts any bearer token. It checks that a token is present, not that it is valid. For an echo service like httpbin that is to be expected; on a real API it is the difference between authentication and a header check.
Not tested: the four state-changing verbs, an expired token, another user's token, rate limiting.
endpoint:
id: whoami
method: GET
path: /bearer
summary:
pass: 8
fail: 1
skipped: 4
manual: 6
checks[13]{id,result,detail}:
V-options,pass,status 200 in 655ms
V-post,skipped,state-changing (POST)
V-put,skipped,state-changing (PUT)
V-patch,skipped,state-changing (PATCH)
V-delete,skipped,state-changing (DELETE)
A-none,pass,status 401 in 605ms
A-invalid,fail,status 200 in 605ms
D-baseline,pass,status 200 in 142ms
D-content-type,pass,"content-type \"application/json\", body is JSON"
D-captures,pass,""
E-no-5xx,pass,""
E-no-leak,pass,""
R-duration,pass,142ms
failures[1]{id,title,expected,actual,note}:
A-invalid,Request with an invalid token is rejected,"status in [401, 403]",status 200 in 605ms,"{\"authenticated\":true,\"token\":\"[REDACTED]\"}"
hint: "4 state-changing probes not sent; ask the user, then rerun with includeDestructive: true"How this was recorded: a script drove the built server over MCP stdio and saved the tool output shown above, unedited. Vander's reply was then written by Claude from that output, following the vander prompt. Every number in the reply comes from the output; timings will differ on your machine.
Related MCP server: fetchsandbox-mcp
1. The agent chooses; the server executes. The agent picks a requestId, and the server builds and sends the request from the YAML. There is no hand-written curl in the chat to get subtly wrong, and the same call gives the same request tomorrow.
2. Tokens are a budget. responseDetail, jsonPathSelect and maxBodyChars decide how much of a response comes back; execute_api_flow runs a whole scenario in one call; results are encoded as TOON rather than JSON.
3. A heuristic is worth more than a personality. Vander is a persona, but what he does is fixed: a checklist built by code and verdicts computed from status codes and timings. Research on personas in prompts found they do not, by themselves, make a model more accurate (sources), so the personality is there for the conversation and the rigour lives in run_vander_checks.
You test an API by talking to your agent. Three pieces make that possible:
Piece | Where | What it is | If you know Postman |
Definitions |
| Your requests, described once and committed with the code. | The collection |
Secrets and environments |
| Base URLs, tokens and passwords. Stays on your machine. | The environment |
The conversation | Your MCP client | You ask in plain language; the agent calls this server; the server sends the request. | Send, Runner and the Tests tab |
Requires Node.js ≥ 20.
1. Build the server and register it in your MCP client.
npm ci
npm run build{
"servers": {
"conversational-api-test-mcp": {
"type": "stdio",
"command": "node",
"args": ["/absolute/path/to/conversational-api-test-mcp/dist/index.js"]
}
}
}2. Open the project whose API you want to test and say hi Vander.
He explains the setup, checks which pieces your project already has, and offers to create the missing ones. Accepting runs init_workspace, which writes the three things below and never overwrites a file that exists. You can also create them by hand.
3. The .mcp/api/ folder and your first YAML. One file per service. Each request gets an id, which is how you and the agent refer to it.
# .mcp/api/weather.yaml
version: "1"
service: weather
base_url: "{{BASE_URL}}"
endpoints:
- id: get_token
method: POST
path: /oauth/token
form:
grant_type: client_credentials
client_id: "{{CLIENT_ID}}"
client_secret: "{{CLIENT_SECRET}}"
capture:
TOKEN: $.access_token
- id: forecast
method: GET
path: /forecast
params:
city: lisbon
auth: Bearer {{TOKEN}}
auth_dependency: get_token
flows:
smoke:
steps:
- requestId: forecast
assert:
status: 200
jsonPathExists: $.daysYou rarely have to write this by hand. Paste a cURL command, paste a whole Postman collection (the exported JSON), or point at an OpenAPI / Insomnia file, and the server writes the YAML for you. Tokens that come along are moved to .env.mcp.local and replaced by {{VARIABLE}}, so the YAML stays safe to commit.
4. The .env.mcp.local file. Create it at the project root, next to .mcp/. It holds what {{...}} stands for. You fill it in yourself, it must be in .gitignore, and its values never go into the chat.
# .env.mcp.local
BASE_URL=https://api.example.com/v1
CLIENT_ID=...
CLIENT_SECRET=...
STAGING_BASE_URL=https://staging.example.com/v1A prefix turns one YAML into several environments: after "use staging", {{BASE_URL}} reads STAGING_BASE_URL first and falls back to BASE_URL.
5. Ask. No file to write yet? init_workspace drops in a demo against httpbin.org that runs without any secret, and examples/ has three more you can copy into .mcp/api/.
Each line is something you would otherwise do by hand in an API client.
You say | What happens | In Postman you would |
"Here is my Postman collection" + the JSON, or the path to it | Converts a collection, an OpenAPI spec or an Insomnia export to YAML. | Import |
"Turn this cURL into a request" + the command | Creates the request in a YAML; any token in it goes to | Import → Raw text |
"Run | Sends that one request and summarises the response. | Click Send |
"Run the smoke flow" | Runs the requests of a flow in order, stopping at the first failure. | Collection Runner |
"Log in and list the orders" | Runs the login first, keeps the token, uses it, and logs in again on a | Pre-request script |
"Create a post, then fetch it by the id that came back" | Captures a value from one response and uses it in the next request. |
|
"Use staging" | Switches the active environment for the following requests. | Environment dropdown |
"Check that it returns 200 and has a | Asserts on status and on a JSONPath. |
|
"Start the export and wait until it is ready" | Polls a request until a field appears. |
|
"Show me what | Builds the request without sending it, credentials hidden. | Console |
"Add a request that creates an order with these fields" | Writes a new entry to the YAML, showing a preview first. | New request |
"Run the smoke eval of the assistant" | Sends each question several times and passes it on a pass rate; checks answers, citations and latency by code. | — |
"Vander, is | Reviews the endpoint on six axes and reports evidence. | — |
Tool | Purpose |
| List YAMLs under |
| Cheap triage: endpoint ids, variable keys, flow names. |
| Full, validated definition. |
| Run one endpoint. |
| Run several endpoints in one call — inline |
| Show the request that would be sent, without sending it. |
| Assert on the last response: status, latency and value checks. |
| Evaluate an endpoint whose answer varies (LLM / RAG / search): cases × repeats, pass rate, optional samples for the agent to judge. |
| Select the active environment ( |
| Session variables. |
| Which variable keys are available from where. |
| Create |
| Create / append definitions (dry-run by default). |
| Merge many YAMLs into fewer (plan, then apply). |
| Hands the agent the Vander persona when you address him by name. |
| VANDER review of one endpoint: checklist, then automatic execution — one row per check, the id prefix being the axis. |
| Turn a pasted |
| Import Postman, OpenAPI or Insomnia — from a file or from pasted text. |
Recommended order: list_api_definitions → summarize_api_definition → set_environment (if needed) → execute_api_request or execute_api_flow.
Vander is a persona shipped as an MCP prompt: a senior API QA engineer you talk to instead of issuing tool calls yourself. In clients that expose MCP prompts it shows up as a command (for example /vander), optionally with a definition path and an endpoint id. He reviews an endpoint through the VANDER heuristic:
Axis | Question | Checked automatically |
Verbs | What does the path do with methods it does not declare? | Undeclared methods are rejected (405/404/501); |
Authorization | Who can call it? | No credentials and an invalid token are rejected (401/403). |
Negative | What happens with bad input? | Each top-level body field removed in turn is rejected (4xx). |
Data | Does the response say what it should? | Baseline succeeds, |
Errors | Does it fail well? | Malformed JSON is a client error; no probe causes a 5xx or leaks a stack trace. |
Responsiveness | Is it fast enough? | Baseline answers within |
Each axis also carries manual ideas (other users' tokens, boundary values, idempotency, rate limiting…) that Vander explores with the regular tools.
In clients without prompt support — or when you would rather just talk — say his name: "hi Vander, review whoami". The server's instructions tell the agent to call summon_vander, which hands it the same brief.
The check tools work without the persona too:
plan_vander_checks returns the checklist for a requestId and sends nothing.
run_vander_checks executes the automatic checks and returns pass / fail / skipped per check (the id prefix is the axis), with the detail of each failure listed apart. Probes never capture variables. Anything that sends POST, PUT, PATCH or DELETE is skipped unless includeDestructive: true, so reviewing a write endpoint is an explicit decision.
VANDER builds on Stuart Ashman's VADER heuristic and adds an explicit Negative axis — see where the ideas come from.
{{KEY}} is resolved from, in increasing priority: YAML variables → .env.mcp.local → session variables (captures and set_environment_variable).
After set_environment (e.g. STAGING), {{BASE_URL}} resolves STAGING_BASE_URL first and falls back to BASE_URL.
Unresolved placeholders are left as literal {{KEY}} so the problem is visible.
Macros: {{$uuid}}, {{$timestamp}}, {{$date}}, {{$date:YYYY-MM-DD HH:mm:ss}}.
{{env.NAME}} reads the server's process.env, but only for names listed in MCP_API_ENV_PASSTHROUGH.
base_url may carry a path prefix (https://host/api/v1); path is appended to it. An absolute path overrides base_url.
params is sent as the query string; headers, body (JSON) and form (URL-encoded) are interpolated.
capture maps a session variable name to a JSONPath on the response; assert checks status, latency and values — see value checks.
auth: Bearer {{TOKEN}} sets the Authorization header.
auth_dependency: <endpoint id> runs that endpoint first when its captured variables are missing, and again after a 401 (disable with auth_retry_on_401: false).
digest_auth: { username, password } performs HTTP Digest.
Each step is an endpoint id or an object:
flows:
create_and_wait:
steps:
- create_job
- requestId: get_job
poll: { untilJsonPath: "$.finishedAt", maxAttempts: 10, delayMs: 2000 }
retry: { max: 3, delayMs: 500 }
acceptStatus: [200]
assert: { status: 200, jsonPathExists: "$.result" }
optional: falseassert (on a request, on a flow step, or through assert_response) takes status, jsonPathExists, maxDurationMs and a list of checks. Each check reads the value at a JSONPath path — or the whole body as text when path is omitted — and every operator in it must hold. All failing checks are reported, not just the first.
Operator | Holds when |
| The text has all of / one of / none of the given strings. |
| The text matches the regular expression. |
| Makes the four above case-insensitive. |
| The value is exactly this (any JSON value). |
| The number is within the bounds. |
| The string or list has that many characters / items. |
| The list at |
| Every value at |
An operator the server does not know is an error when the YAML is read, never a silent pass.
A request to an LLM, a RAG or a search endpoint can come back different every time, so one green run proves little. An eval sends one request over several cases, each repeated, and passes a case on its pass rate:
evals:
smoke:
requestId: ask
repeat: 3 # each case is sent 3 times
passRate: 0.66 # and passes when 2 of the 3 runs satisfy `expect`
expect: # applied to every case
status: 200
maxDurationMs: 8000
checks:
- path: $.citations
subsetOf: $.sources[*].id # no invented citation
judge: # optional: samples for the agent to grade
answerPath: $.answer
contextPath: $.sources[*].text
questionVariable: question
cases:
- name: refund_window
variables: { question: How many days do I have to ask for a refund? }
reference: 30 days from delivery.
expect:
checks:
- { path: $.answer, contains: "30" }
- { path: $.sources[*].id, includesAll: [policy-refunds, faq-returns], minRatio: 0.5 }
- name: out_of_scope
variables: { question: Who will win the next election? }
expect:
checks:
- { path: $.answer, matches: "(don't|do not|cannot) (know|answer)", ignoreCase: true }
- { path: $.citations, maxLength: 0 }Run it with "run the smoke eval" (run_eval + evalName), or pass requestId and cases inline. The result has one row per case (passed: 2/3, latency, how many different answers came back), the distinct failures with how often each happened, and p50 / p95 latency.
Two kinds of verdict come out of it, and they are kept apart:
Checked by code — everything under expect. Same input, same verdict: status, latency, words that must or must not appear, a refusal for out-of-scope questions, expected documents among the retrieved ones, citations that point at retrieved documents.
Judged by the agent — with judge, the result carries one sample per case (question, answer, retrieved passages, reference) and a rubric: faithfulness, relevance, context_relevance, correctness, or criteria in your own words. The server calls no model; the agent you are talking to does the grading, so the verdict depends on that model and is reported as judgement.
Things to know:
Every run is a real request, usually a paid one. run_eval refuses to start when cases × repeat exceeds maxRequests (default 30).
Eval runs do not capture variables or replace the session's last response; auth_dependency still logs in when needed.
A streamed answer (text/event-stream) is folded into { text, eventCount, events }, so $.text is the answer and events keeps what was not a text delta (sources, usage, stop reason). Set sse.textPath on the request when the delta sits somewhere unusual.
examples/rag.example.yaml is a complete starting point.
responseDetail: "minimal" returns status, duration and captures only; "summary" (default) adds the body, capped at 8,000 chars, and the headers that usually matter (content-type, location, retry-after, rate limits…); "full" returns every header and raises the cap to 50,000.
The body comes back once: bodyJson for JSON, bodyPreview for text. Both appear only when JSON exceeds the cap (truncated preview plus topLevelKeys).
jsonPathSelect projects the body before it is serialized. On an execute_api_flow step it returns that step's body, so reading it needs no second call.
execute_api_flow replaces N tool calls with one.
Parsed definitions and .env.mcp.local are cached in memory and invalidated by file mtime.
The server runs locally with your privileges and is driven by an LLM, so treat API responses and definitions as untrusted input.
Redaction. Auth headers, values under credential-looking JSON keys (password, token, secret, api_key, …), JWT-looking strings, credential query parameters and captured credentials are returned as [REDACTED]. The real values stay in the session and are still used by later requests. Redaction is name- and shape-based, so it is a safety net, not a guarantee.
No implicit environment access. process.env is not part of the interpolation context; only names you list in MCP_API_ENV_PASSTHROUGH are reachable, via {{env.NAME}}.
Responses are data. Values captured from a response are inserted literally and never re-expanded as templates.
Writes are confined. Definition tools write only under .mcp/api/ and default to dry-run. init_workspace also creates .env.mcp.local and adds it to .gitignore, and never overwrites an existing file. The import tools append the credentials they lift to .env.mcp.local, never replacing a key that is already there.
Optional host allowlist. MCP_API_ALLOWED_HOSTS restricts requests — including every redirect hop — to the listed hostnames. It is off by default and is not a complete SSRF defence (no private-range or DNS-rebinding checks).
Environment variable | Effect |
| Default |
| Comma-separated hostnames requests may target. Unset = any host. |
| Comma-separated env var names (trailing |
| Response size cap. Default 10 MB. |
|
|
Nothing here was invented from scratch. This is what the project borrows, from whom, and what it changes.
Idea in this project | Source | What was taken, and what was changed |
The VANDER axes | Stuart Ashman, VADER – a REST API test heuristic (QA Matters, 2016) | The five original axes — Verbs, Authorization, Data, Errors, Responsiveness — are his. This project adds Negative as a sixth and turns part of each axis into executable checks. |
The Negative axis | Gwen Diagram & Ash Winter's BINMEN (Boundary, Invalid entries, NULL, Method, Empty, Negative), as listed in the Ministry of Testing Test Heuristics Cheat Sheet | The framing of negative input as its own concern. Only "missing field" is automated today; the rest are offered as manual ideas. |
Splitting input from output concerns | Amber Race's POISED (Parameters, Output, Interop, Security, Errors, Data), same cheat sheet | Informs the manual ideas under Data and Negative. |
Which probes are "destructive" | RFC 9110, HTTP Semantics §9.2.1 (safe methods) |
|
Expected statuses | RFC 9110 §15.5.6 ( | An undeclared method should get |
What the Authorization axis looks for | OWASP API Security Top 10 – 2023, API2 Broken Authentication | Automated: no credentials, invalid token. API1 and API5 (object- and function-level authorization) need a second identity, so they stay manual. |
Host allowlist, response size cap | OWASP API7 (Server Side Request Forgery) and API4 (Unrestricted Resource Consumption) | Applied to this server itself, since it makes requests on an agent's behalf. |
Vander as an MCP prompt | Prompts are "user-controlled": the user picks them explicitly, typically as a slash command. That is why the persona is opt-in rather than baked into every conversation. | |
Persona for tone, code for verdicts | Zheng et al., When "A Helpful Assistant" Is Not Really Helpful (Findings of EMNLP 2024) | They report that adding a persona to the system prompt did not improve accuracy over no persona. So nothing Vander asserts depends on the persona. |
TOON output | Used as-is for tool results. Its authors report the largest savings on uniform arrays and little or none on deeply nested data; this project has not benchmarked it independently. |
VANDER is this project's name for the extended heuristic and has no affiliation with the authors above.
Symptom | Check |
Empty definition list | Is |
|
|
| Key name, environment prefix ( |
A value shows as | Expected for credentials. It is still used in requests. |
Command | Description |
| Compile TypeScript to |
| Run from source with |
| Run the test suite ( |
| ESLint. |
Assert on the last HTTP response: status, jsonPathExists, maxDurationMs and value checks (contains, regex, equality, ranges, list membership). Reports every check that failed. Run after execute_api_request.
| Name | Required | Description | Default |
|---|---|---|---|
| checks | No | Value checks, each {path (JSONPath; omit = whole body), contains | containsAny | notContains | matches | equals | min | max | minLength | maxLength | includesAll | includesAny | subsetOf, ignoreCase, minRatio}. | |
| status | No | ||
| maxDurationMs | No | ||
| workspaceRoot | No | Optional when MCP_WORKSPACE_ROOT is set. | |
| jsonPathExists | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses two behavioral traits: it operates on implicit prior state ("the last HTTP response", implying execute_api_request must have run) and it is aggregate rather than fail-fast ("Reports every check that failed"). It says nothing about what a passing result returns, how missing prior state is handled, or any permission/rate constraints.
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 short sentences, front-loaded with the core purpose, then the operator vocabulary, then the sequencing constraint. Every clause carries information; nothing is padding.
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 an assertion tool with no output schema and no annotations, the description covers the input surface adequately but leaves the result contract thin: "reports every check that failed" does not describe the shape of a success response or how failures are reported structurally. Parameter coverage of 40% also leaves gaps the description only partly fills.
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 low at 40%, so the description must compensate. It does name four of the five parameters (status, jsonPathExists, maxDurationMs, checks) and the check operators, which helps, but it adds no syntax or semantic detail beyond what the schema already documents for `checks`, and it omits `workspaceRoot` 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?
States a specific verb (assert) against a specific resource (the last HTTP response) and enumerates the assertable facets: status, jsonPathExists, maxDurationMs, and value checks. It is distinguishable from execute_api_request, but it does not differentiate itself from the related verification siblings such as run_vander_checks, plan_vander_checks, or run_eval.
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?
"Run after execute_api_request" gives explicit sequencing context that an agent needs, which is more than most assertions tools provide. However, it names no exclusions or alternatives (e.g. when to prefer run_vander_checks/plan_vander_checks over this raw assertion), so it stops short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Turn a Postman collection, an OpenAPI/Swagger spec or an Insomnia export into a YAML definition under .mcp/api/. Give legacyRelativePath for a file in the workspace, or legacyContent with the JSON/YAML text the user pasted. Literal credentials found in headers or auth are moved to .env.mcp.local and replaced by {{VARIABLE}}. Refuses to replace an existing file unless overwrite is true. Apidog: export as OpenAPI or Postman first.
| Name | Required | Description | Default |
|---|---|---|---|
| overwrite | No | Replace outputRelativePath if it already exists. | |
| serviceName | No | ||
| legacyContent | No | The collection / spec itself (JSON or YAML text), when the user pasted it instead of pointing at a file. Provide this or legacyRelativePath. | |
| workspaceRoot | No | Absolute project path (optional when MCP_WORKSPACE_ROOT is set). | |
| legacyRelativePath | No | Path to a Postman / OpenAPI / Insomnia file in the workspace. | |
| outputRelativePath | No | Where to write, under .mcp/api/. Defaults to .mcp/api/imported.yaml |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does so substantively: credentials in headers/auth are relocated to `.env.mcp.local` and replaced with `{{VARIABLE}}`, and the tool refuses to overwrite unless `overwrite` is true. Missing only error/permission behavior and what a successful result looks like.
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?
Roughly five tight sentences, front-loaded with the core transformation, then input selection, side effects, safety rule, and a source-specific caveat. No filler.
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?
Covers inputs, side effects, and output location well for a 6-param tool with no annotations. With no output schema, the description could say more about the return value/confirmation an agent should expect, which is the one remaining 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 coverage is 83% so the baseline is 3, and the description adds value beyond the schema by framing the legacyRelativePath/legacyContent alternation as an either/or and spelling out the overwrite refusal semantics. It does not clarify `serviceName` or `workspaceRoot`, leaving a small 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 transformation (Postman/OpenAPI/Insomnia → YAML under `.mcp/api/`) with a clear verb and resource. An agent can distinguish this from siblings like import_curl, list_api_definitions, and upsert_canonical_api_definition immediately.
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 routes the agent between `legacyRelativePath` (file in workspace) and `legacyContent` (pasted text), and adds the Apidog prerequisite ('export as OpenAPI or Postman first'). No exclusion against sibling import tools (e.g., import_curl), which keeps it from a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find Postman collections, OpenAPI/Swagger, or Insomnia exports.
| Name | Required | Description | Default |
|---|---|---|---|
| maxDepth | No | ||
| maxFiles | No | ||
| workspaceRoot | No | Optional when MCP_WORKSPACE_ROOT is set. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are supplied, so the description carries the full behavioral burden, yet it only implies a read-only search. It says nothing about traversal behavior, depth/file limits, permission needs, or whether the workspace is scanned or the network is queried.
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?
A single front-loaded sentence with zero filler. It is efficient, though the terseness is the cause of the missing usage and parameter guidance rather than a virtue in itself.
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 3-parameter tool with no annotations, no output schema, and 33% schema coverage, one sentence is inadequate. The agent does not know what a result looks like, how deep discovery recurses, or when to reach for this tool instead of its siblings.
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 33% (just workspaceRoot), and the description adds no parameter meaning at all. maxDepth and maxFiles remain undocumented in both places, leaving the agent to guess their effect on discovery scope.
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 verb 'Find' plus the concrete resource list (Postman collections, OpenAPI/Swagger, Insomnia exports) states exactly what the tool returns. The legacy-source framing implicitly separates it from list_api_definitions and convert_legacy_to_canonical, though it never names a sibling 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?
There is no statement of when to use this versus list_api_definitions (canonical definitions) or convert_legacy_to_canonical. No prerequisites, no exclusion conditions, no mention that discovery typically precedes conversion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Build the URL, method, headers and body preview for a requestId without sending the request. Credentials in headers, query string and body are redacted.
| Name | Required | Description | Default |
|---|---|---|---|
| requestId | Yes | ||
| maxBodyChars | No | ||
| workspaceRoot | No | Optional when MCP_WORKSPACE_ROOT is set. | |
| definitionRelativePath | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does disclose two non-obvious traits: no request is actually sent, and credentials in headers, query string and body are redacted. It does not cover required permissions, behavior for an unknown requestId, or how truncation interacts with maxBodyChars.
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 tightly written sentences with no filler. The core purpose and the no-send guarantee are front-loaded, and the redaction caveat follows immediately.
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?
Having no output schema, the description usefully states the return shape (URL, method, headers, body preview) and the redaction guarantee. But for a 4-param tool with 25% schema coverage it leaves how definitionRelativePath, workspaceRoot and maxBodyChars shape the result unexplained.
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 25% (only workspaceRoot is documented in-schema), so the description should compensate but does not. It never mentions maxBodyChars and its truncation effect, workspaceRoot, or what definitionRelativePath contributes, mentioning only requestId implicitly.
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 gives a specific verb (build) and enumerates the exact artifacts produced (URL, method, headers, body preview), plus the key qualifier 'without sending the request'. It implicitly distinguishes itself from execute_api_request, though it never names that sibling 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?
The phrase 'without sending the request' implies this is a safe preview/inspection step before execution, which is useful context. However, it never states when to prefer this over execute_api_request, nor any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a sequence of requestIds in a single MCP round trip. Pass inline steps, or flowName to run a flow declared under flows: in the definition. Each step supports retry, poll (via jsonPath), an inline assert (same shape as assert_response), optional, and jsonPathSelect to get that step's body back ($ for all of it) without a follow-up call. stopOnError halts at the first failing required step.
| Name | Required | Description | Default |
|---|---|---|---|
| steps | No | Inline steps. Provide either `steps` or `flowName`. | |
| flowName | No | Name of a flow declared under `flows:` in the definition. | |
| stopOnError | No | ||
| workspaceRoot | No | Optional when MCP_WORKSPACE_ROOT is set. | |
| responseDetail | No | minimal: requestId/ok/status per step. summary: + durationMs and captured values. per_step: + each step's body (capped). A step's own `jsonPathSelect` returns its body at any level. | summary |
| definitionRelativePath | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does reasonably well: it discloses step-level behaviors (retry, poll via jsonPath, inline assert, optional, jsonPathSelect) and that `stopOnError` halts at the first failing required step. It omits auth/permission needs and write-vs-read safety, but the operational behavior is substantially covered.
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 sentences, front-loaded with the purpose and packed with high-value detail using no filler. The parameter capabilities are enumerated compactly, and nothing is redundant with the schema's own descriptions.
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 complex nested-steps tool with no output schema, the description is fairly complete: it covers steps, flowName, stopOnError, and the per-step features. It leaves responseDetail, definitionRelativePath, workspaceRoot, and acceptStatus to the schema, which is acceptable but leaves minor gaps given 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?
At 67% schema coverage the description meaningfully compensates: it defines the `steps` vs `flowName` alternative, explains `jsonPathSelect` ("$ for all of it") and its follow-up-call avoidance, and cross-references `assert` as "same shape as assert_response." This adds semantics beyond the schema for several of the six 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?
States a specific verb and resource with scope: "Run a sequence of requestIds in a single MCP round trip." This clearly differentiates the batch/flow concept from a single-request tool, though it never names the sibling (execute_api_request) it contrasts with, so the differentiation is implicit rather than explicit.
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 explains HOW to invoke (inline `steps` vs `flowName`) but not WHEN to choose this tool over execute_api_request, dry_run_request, or run_vander_checks. Usage context is only implied by the single-round-trip framing, with no exclusions or explicit alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send one request from a YAML definition. Variables resolve YAML < .env.mcp.local < session (after set_environment, {ENV}_KEY wins over KEY); an unresolved placeholder is sent as the literal {{KEY}}. Runs auth_dependency first when needed, retries once on 401, applies capture and assert. The body comes back once: bodyJson for JSON that fits the cap, bodyPreview for text; JSON over the cap gives a truncated bodyPreview plus bodyJson.topLevelKeys — narrow it with jsonPathSelect. responseDetail: minimal = status only; summary = body (8k chars) and the headers that matter; full = every header, 50k chars.
| Name | Required | Description | Default |
|---|---|---|---|
| requestId | Yes | ||
| timeoutMs | No | ||
| maxBodyChars | No | Character cap for the returned body (after jsonPathSelect, when used). | |
| workspaceRoot | No | Optional when MCP_WORKSPACE_ROOT is set. | |
| jsonPathSelect | No | JSONPath to project the response body before returning it. | |
| responseDetail | No | summary | |
| definitionRelativePath | Yes | e.g. .mcp/api/default.yaml |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does substantial work: variable resolution precedence, literal {{KEY}} fallback, auth_dependency execution, single 401 retry, capture/assert application, and the body-return/cap semantics. It does not disclose whether the request can mutate state (POST/PUT/DELETE) or what permissions the tool needs, which is the main remaining gap.
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?
Dense but front-loaded: the primary action leads, then resolution rules, then return-shape behavior. Every sentence carries information with essentially no filler, though the single unbroken paragraph of nested clauses is harder to scan than it needs to be.
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 7-parameter tool with no output schema, the description does explain the return shape (bodyJson vs bodyPreview, truncation, topLevelKeys) and detail levels, which is exactly what an agent needs. It omits error behavior beyond the 401 retry and any statement of side effects, but is otherwise complete enough to call correctly.
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 57%, so the description compensates beyond the schema: it defines the responseDetail levels (minimal/summary/full) with concrete size limits, explains jsonPathSelect narrowing, and clarifies that maxBodyChars applies after jsonPathSelect. It adds little for requestId, timeoutMs, or workspaceRoot, but the value added elsewhere is real.
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: 'Send one request from a YAML definition.' The singular 'one request' implicitly distinguishes it from the multi-step sibling execute_api_flow, though it never names that alternative. Clear purpose, but sibling differentiation is left to inference.
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 (single request from a YAML definition, run auth_dependency first) but never states when to pick this over execute_api_flow, dry_run_request, or explain_request_context. No explicit when/when-not guidance; usage is only implied by the automation behavior described.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Summarize YAML keys, .env.mcp.local keys, session keys, and optional endpoint snippet.
| Name | Required | Description | Default |
|---|---|---|---|
| requestId | No | ||
| workspaceRoot | No | ||
| definitionRelativePath | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. 'Summarize' implies a read-only aggregation, but the description does not state side effects, permission requirements, or whether the required definitionRelativePath must resolve to a real file. It only hints at output content, leaving most behavior undisclosed.
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?
A single front-loaded sentence with no filler. It is efficient, though extremely terse for a tool with an undocumented required parameter.
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 tool with a required parameter, three undocumented params at 0% coverage, no annotations, and no output schema, the description is too thin. An agent cannot determine how to satisfy definitionRelativePath or how the three context sources are resolved and returned.
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% across three parameters, including the required definitionRelativePath, yet the description says nothing about what any parameter means or does. The mention of 'optional endpoint snippet' does not map clearly to requestId, workspaceRoot, or definitionRelativePath, so the description fails to compensate for the total schema 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?
The description states a specific verb ('Summarize') and enumerates the exact resources being summarized (YAML keys, .env.mcp.local keys, session keys, endpoint snippet), so an agent can form a concrete expectation of the output. It does not, however, distinguish this tool from siblings like summarize_api_definition or get_environment_variable, which cover overlapping config/key territory.
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?
There is no guidance on when to use this tool versus alternatives such as summarize_api_definition, get_environment_variable, or read_api_definition, nor any stated prerequisites or context. The agent is left to infer usage entirely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a session variable set by capture or set_environment_variable. Credential-looking values come back as [REDACTED] with masked: true.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| workspaceRoot | No | Optional when MCP_WORKSPACE_ROOT is set. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full behavioral burden. It usefully discloses the redaction behavior ('[REDACTED]' with `masked: true`), which is exactly the kind of trait annotations would otherwise cover, but says nothing about error behavior for missing variables, permissions, or session scoping.
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 tight sentences, zero filler, with the read purpose front-loaded and the redaction caveat immediately after. Nothing needs trimming or moving.
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?
With no output schema and no annotations, the description partially covers the return shape via `masked: true` and explains the source of values. It is nearly complete for a simple single-value read, though it omits failure behavior for unset or unknown variable names.
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%: workspaceRoot is documented in the schema, but `name` has no description anywhere. The description adds no semantics for the parameter—no key format, case sensitivity, or match rules against the set key—so it fails to compensate for 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?
Specific verb+resource: 'Read a session variable'. It also disambiguates from the sibling setter by naming 'set_environment_variable' and 'capture' as the producers of the value, so an agent can route correctly without opening the schema.
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?
Usage is implied by naming the setting tools as the source of the value, which suggests reading after capture/set. But there is no explicit when/when-not guidance (e.g., what to do if the variable was never set, or whether a workspace-scoped read differs).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Turn a curl command the user pasted into a request in a YAML definition under .mcp/api/ (creates the file, or appends to it). Method, URL, query string, headers and JSON / form body are carried over. Credentials (Authorization, cookies, -u, credential-looking fields) are moved to .env.mcp.local and replaced by {{VARIABLE}}, so the YAML stays safe to commit. Fails if requestId already exists.
| Name | Required | Description | Default |
|---|---|---|---|
| curl | Yes | The curl command, exactly as the user pasted it. | |
| requestId | Yes | Id for the new request, e.g. get_user. Letters, digits and underscores. | |
| description | No | ||
| workspaceRoot | No | Absolute project path (optional when MCP_WORKSPACE_ROOT is set). | |
| definitionRelativePath | No | YAML to create or append to, under .mcp/api/. | .mcp/api/imported.yaml |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full disclosure burden and does so well: file creation vs. append behavior, credential relocation to `.env.mcp.local` with `{{VARIABLE}}` substitution, which parts of the curl are carried over, and the duplicate-requestId failure mode. These are exactly the side effects and side-channel consequences an agent needs before invoking.
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, each dense with distinct information, front-loaded with the core transformation and followed by transfer scope, credential handling, and the failure mode. No filler or repetition of the tool name.
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 5-parameter, mutation-style tool with no annotations and no output schema, the description covers behavior, side effects, and the main failure mode well. It does not describe the return value or the semantics of the optional `description` field, which is a minor remaining 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 coverage is 80% and the schema already documents `curl`, `requestId`, and `definitionRelativePath`. The description adds meaning beyond that by clarifying the uniqueness constraint on `requestId` (fails on collision) and the parsing scope of the `curl` payload; only the bare `description` parameter gets no added context.
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 (turn/convert) and resource (curl command into a YAML request definition), and names the destination path `.mcp/api/`. An agent can distinguish this from siblings like `convert_legacy_to_canonical` or `upsert_canonical_api_definition` readily.
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?
Gives clear triggering context (a curl command the user pasted) and a failure condition (requestId already exists), which effectively tells the agent when not to call it. It never names alternative tools for adjacent tasks such as validating a request via `dry_run_request` or editing an existing definition via `upsert_canonical_api_definition`.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create the starting structure in a project: the .mcp/api/ folder, a runnable demo definition (demo.yaml, against httpbin.org) when there is no definition yet, an .env.mcp.local template with commented examples, and the .gitignore line that keeps that file out of git. Never overwrites an existing file. Ask the user before calling it.
| Name | Required | Description | Default |
|---|---|---|---|
| withDemo | No | Also write `.mcp/api/demo.yaml`, a runnable definition against httpbin.org, when the folder has no definition yet. | |
| workspaceRoot | No | Absolute project path (optional when MCP_WORKSPACE_ROOT is set). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden well: it discloses that it never overwrites existing files, that it mutates `.gitignore`, that `.env.mcp.local` contains commented examples, and that user confirmation is required. It stops short of describing the return value or any error behavior, but the destructive-safety profile is unusually well covered.
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 artifact list is front-loaded and the two safety sentences are short and high-value. The opening sentence is dense with parentheticals, but every element earns its place and nothing is padded.
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 zero-required-parameter scaffold tool with no output schema, the description covers what is created, the overwrite policy, and the approval requirement. Only the return value and behavior on partial existing structure are unstated, which is a minor 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 100%, so both parameters are already documented. The description restates the conditional writing of `demo.yaml` and mentions the `MCP_WORKSPACE_ROOT` fallback indirectly, but adds no format or path syntax beyond the schema, so the baseline 3 applies.
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 gives a specific verb ('Create') and enumerates the exact artifacts produced: the `.mcp/api/` folder, `demo.yaml`, `.env.mcp.local`, and the `.gitignore` line. This distinguishes it clearly from siblings like `upsert_canonical_api_definition` or `import_curl`, which operate on existing definitions rather than bootstrapping a project.
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 operative condition ('when there is no definition yet') and imposes an explicit approval gate: 'Ask the user before calling it.' That is clear context for when to invoke it, though it never names an alternative sibling for the case where a definition already exists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List YAML API definition files under .mcp/api/. Returns files (paths), or entries (path/service/summary) with includeCatalogMeta or query; plus totalMatched, truncated and, when capped by maxFiles, a nextCursor to pass back as cursor.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Case-insensitive substring filter on path and on service/summary from _catalog.yaml. | |
| cursor | No | `nextCursor` from the previous page. | |
| fields | No | Keep only these keys of each `entries` item (path/service/summary). | |
| sortBy | No | path | |
| maxFiles | No | Page size. | |
| globPattern | No | glob pattern relative to .mcp/api/ (default "**/*.{yaml,yml}") | |
| workspaceRoot | No | Absolute path to the project root (optional when MCP_WORKSPACE_ROOT is set). | |
| includeCatalogMeta | No | Return service/summary per path from `.mcp/api/_catalog.yaml`, if present. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose the conditional return shapes (`files` vs `entries`), plus `totalMatched`, `truncated`, and `nextCursor` pagination. However, it says nothing about read-only safety, default page size when `maxFiles` is unset, or what happens on an invalid cursor, leaving real gaps for a no-annotation tool.
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?
A single dense sentence with the purpose front-loaded and no filler. It is somewhat run-on in packing return shapes and pagination together, but every clause conveys usable 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?
With no output schema, the description usefully explains return values and pagination, which is the key missing structured data. It is nearly complete for a list tool, lacking only safety/permission context and default-limit behavior.
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 88%, so the schema already documents nearly all eight parameters; baseline is 3. The description reinforces the relationship between `includeCatalogMeta`/`query` and the `entries` shape and the `nextCursor`-to-`cursor` round-trip, but that is largely restating the schema rather than adding new meaning.
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 (List) and resource (YAML API definition files) with an explicit scope (`.mcp/api/`), so an agent can distinguish it from read_api_definition, which reads a single file. It does not name a sibling directly, but the scope makes the passive enumeration role 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?
No when-to-use guidance or alternatives are given; the agent must infer that this is for discovery/enumeration versus reading or converting a definition. There is no mention of prerequisites (e.g. workspaceRoot/MCP_WORKSPACE_ROOT) beyond what the schema itself already provides.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Build the VANDER checklist (Verbs, Authorization, Negative, Data, Errors, Responsiveness) for one requestId, derived deterministically from its definition. Sends nothing. The id prefix is the axis (V-, A-, …). mode: auto (run_vander_checks executes it), destructive (auto, but state-changing) or manual (an idea to explore by hand).
| Name | Required | Description | Default |
|---|---|---|---|
| axes | No | Limit to these VANDER axes (default: all six). | |
| requestId | Yes | ||
| workspaceRoot | No | Optional when MCP_WORKSPACE_ROOT is set. | |
| definitionRelativePath | Yes | e.g. .mcp/api/default.yaml |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden; it discloses that it 'Sends nothing' and is 'derived deterministically', which are genuine non-side-effect traits. However, it omits permission/auth needs and does not describe the resulting artifact beyond id prefixes, leaving meaningful behavioral gaps for a zero-annotation tool.
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 dense sentences, front-loaded with the core action and acronym expansion before the mode caveats. There is little waste, though the mode sentence is somewhat cryptic and could be tightened.
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?
With no output schema and no annotations, the description does explain the return artifact (checklist with axis-prefixed ids) and the no-send behavior. It is largely sufficient for an agent to call the tool, with only the undocumented-in-schema mode reference as a loose end.
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 75%, so the schema already documents axes, definitionRelativePath, and workspaceRoot, making 3 the baseline. The description adds the V-/A- id-prefix mapping for axes but introduces a `mode` field that does not exist in the input schema, so its added parameter value is partly misaligned.
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 and resource: 'Build the VANDER checklist ... for one requestId', and expands the acronym so the agent knows exactly what artifact results. It also names the sibling run_vander_checks as the executor, giving partial differentiation. It stops short of fully contrasting the planning role against the execution role.
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 mode vocabulary (auto/destructive/manual) implies when the checklist is a plan versus an action, and 'run_vander_checks executes it' hints at the plan-then-execute split. But there is no explicit 'use this before run_vander_checks' instruction or exclusion of alternatives, so usage must be inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read and validate a whole API YAML definition. Prefer summarize_api_definition for triage.
| Name | Required | Description | Default |
|---|---|---|---|
| workspaceRoot | No | Optional when MCP_WORKSPACE_ROOT is set. | |
| definitionRelativePath | Yes | Path under workspace, e.g. .mcp/api/default.yaml |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses one trait beyond the name — that the read also validates the YAML — which usefully signals it can fail on malformed definitions. However it says nothing about whether it mutates anything, what a validation failure returns, or error semantics, leaving significant gaps for a zero-annotation tool.
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 short sentences with zero filler. The primary action is front-loaded and the sibling routing note follows immediately after, so an agent gets both facts in one pass.
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?
There is no output schema and no annotations, so the description is the only place to explain what 'read and validate' returns (parsed definition? validation errors? full text?). It covers the action and the sibling choice but omits return/error behavior and any size or scope caveats for large definitions.
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 both parameters (workspaceRoot, definitionRelativePath) are already documented in the schema, including the MCP_WORKSPACE_ROOT fallback. The description adds no path syntax, format, or interpretation detail beyond that, so the baseline 3 applies.
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 pair (read and validate) against a specific resource (a whole API YAML definition). The word 'whole' plus the explicit pointer to summarize_api_definition makes its scope distinguishable from the summarizing sibling without opening either schema.
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?
Names an alternative (summarize_api_definition) and the condition that selects it ('for triage'), which is genuine routing guidance. It stops short of stating when-not to use this tool or any prerequisites (e.g. path/workspace requirements), so it is clear but not complete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Plan or apply merging multiple YAML definitions into fewer files. mode plan (no writes) or apply (requires confirm true). groupBy manual_groups (requires manualGroups with targetRelativePath + sourceGlobs relative to .mcp/api/) or same_service_field (auto groups files sharing non-empty service into .mcp/api/_consolidated/*.yaml). Conflicts (duplicate endpoint id across files, mismatched base_url/service/variables) block apply. Optional deleteSourcesAfterMerge or moveSourcesToArchive (mutually exclusive).
| Name | Required | Description | Default |
|---|---|---|---|
| mode | Yes | ||
| confirm | No | ||
| groupBy | Yes | ||
| manualGroups | No | ||
| workspaceRoot | No | Optional when MCP_WORKSPACE_ROOT is set. | |
| moveSourcesToArchive | No | ||
| deleteSourcesAfterMerge | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses that plan performs no writes, that apply needs confirm true, that conflicts (duplicate endpoint id, mismatched base_url/service/variables) block apply, and that deleteSourcesAfterMerge and moveSourcesToArchive are mutually exclusive. It does not spell out the exact destruction semantics of deleteSourcesAfterMerge, leaving a small gap.
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?
A single dense paragraph that front-loads the core purpose before drilling into modes, grouping, and conflict rules. It is telegraphic in places but every clause adds actionable information with no filler.
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 7-param mutation tool with no annotations and no output schema, the description covers modes, prerequisites, conflict-blocking behavior, and side-effect options well. Minor gaps remain: workspaceRoot handling and what a plan run returns to the caller.
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 14%, so the description must compensate, and it does for 6 of 7 params: mode, confirm, groupBy, manualGroups (targetRelativePath + sourceGlobs, relative to .mcp/api/), and both cleanup flags with their mutual exclusivity. Only workspaceRoot is left undocumented beyond the schema's env-var note.
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 (merge) and resource (multiple YAML API definitions into fewer files), plus the two operating modes. An agent can immediately distinguish this from siblings like upsert_canonical_api_definition or convert_legacy_to_canonical without opening any schema.
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 contrasts plan (no writes) vs apply (requires confirm true), and details when each groupBy value applies and what each requires. It stops short of naming sibling alternatives or stating when this tool is the wrong choice, but the internal mode routing is very clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Evaluate an endpoint whose answer varies (LLM / RAG / search) — or any endpoint over many inputs — in one call. Runs each case repeat times and passes it when passRate of the runs satisfy expect; returns one row per case, the distinct failures, latency p50/p95 and how many different answers came back. With judge it also returns question / answer / retrieved passages for you to grade what code cannot (faithfulness, relevance). Runs do not capture variables or replace the session's last response. Every run is a real, possibly paid, request.
| Name | Required | Description | Default |
|---|---|---|---|
| cases | No | Inline cases: {name, variables: {question: "…"}, expect, reference}. expect = {status, jsonPathExists, maxDurationMs, checks: [{path (JSONPath; omit = whole body), contains | containsAny | notContains | matches | equals | min | max | minLength | maxLength | includesAll | includesAny | subsetOf (another JSONPath), ignoreCase, minRatio}]} | |
| judge | No | Return samples for you to grade: {answerPath, contextPath, questionVariable, criteria: [faithfulness | relevance | context_relevance | correctness | your own rubric]}. | |
| expect | No | Applied to every case. | |
| repeat | No | Times each case is sent (default 1, or the eval's). | |
| evalName | No | Eval declared under `evals:` in the definition. Otherwise pass `requestId` + `cases`. | |
| passRate | No | Share of a case's runs that must pass (default 1). | |
| caseNames | No | Run only these cases. | |
| requestId | No | ||
| timeoutMs | No | ||
| concurrency | No | ||
| maxRequests | No | Refuse to start when cases × repeat exceeds this. | |
| workspaceRoot | No | Optional when MCP_WORKSPACE_ROOT is set. | |
| definitionRelativePath | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so well: it discloses the repeat/passRate pass logic, the return shape (one row per case, distinct failures, p50/p95 latency, distinct-answer count), that runs neither capture variables nor replace the session's last response, and warns every run is a real, possibly paid request.
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 dense sentences that are front-loaded with the core purpose, followed by pass logic, output shape, the judge extension, and caveats. Every sentence earns its place, though the middle sentence is heavily packed.
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 13-parameter tool with no output schema and no annotations, the description covers purpose, return shape, and cost but omits several parameters (concurrency, maxRequests guard behavior, timeoutMs, caseNames, evalName-vs-requestId routing, workspaceRoot). It is adequate for a first call but leaves gaps for full parameterization.
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 69% and the description adds real meaning beyond it: `repeat`/`passRate` are explained through the passing rule, `judge` is described by its returned question/answer/passages, and `cases`/`expect` semantics are tied to per-case evaluation. It doesn't cover routing params like evalName vs requestId.
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 (Evaluate) and resource (an endpoint / any endpoint over many inputs), and scopes it to non-deterministic answers (LLM / RAG / search) versus deterministic inputs. It conveys what the tool does distinctly, though it never names the closest siblings (assert_response, run_vander_checks) to make the boundary explicit.
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?
Clear context for when this applies — endpoints whose answers vary, or any endpoint across many inputs — and it explains the nested `judge` mode for grading what code cannot. There are no explicit exclusions or named alternatives, so the agent must infer when to prefer assert_response or run_vander_checks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute the automatic VANDER checks for one requestId. Returns one row per check (id, whose prefix is the axis; result pass/fail/skipped; detail with the evidence) and failures with expected/actual/body snippet. Probes vary method, credentials and body; they never capture variables or replace the session's last response. State-changing probes (any POST/PUT/PATCH/DELETE) are skipped unless includeDestructive is true — ask the user before enabling it. maxDurationMs is the budget for the Responsiveness check.
| Name | Required | Description | Default |
|---|---|---|---|
| axes | No | Limit to these VANDER axes (default: all six). | |
| requestId | Yes | ||
| timeoutMs | No | ||
| maxDurationMs | No | Budget for the Responsiveness check. | |
| workspaceRoot | No | Optional when MCP_WORKSPACE_ROOT is set. | |
| includeDestructive | No | Also send state-changing probes (POST/PUT/PATCH/DELETE). | |
| definitionRelativePath | Yes | e.g. .mcp/api/default.yaml |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses the return shape (id/result/detail rows plus failures with expected/actual/body snippet), the safety gate on destructive probes, and crucially that probes never capture variables or replace the session's last response. The remaining gap is it doesn't state timeout behavior or permission requirements.
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?
Front-loaded with the purpose in the first clause, then return shape, then behavioral/safety constraints. Dense but every sentence carries information. Slightly long sentences but no filler.
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?
No output schema exists, and the description compensates well by describing both the per-check rows and the failures structure. It covers the destructive-probe safety model and side-effect guarantees. Only timeoutMs semantics and workspaceRoot resolution are left unexplained.
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 71%, so the baseline is around 3. The description adds meaning to includeDestructive (the user-consent requirement) and confirms maxDurationMs governs the Responsiveness check, but requestId and timeoutMs are undocumented in both places. Net value added over the schema is modest.
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 and resource: 'Execute the automatic VANDER checks for one requestId.' An agent knows exactly what the tool does. However, it does not distinguish itself from the close siblings plan_vander_checks or summon_vander, so an agent cannot tell from the description alone which of the three to pick.
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 real guidance for one parameter (state-changing probes are skipped unless includeDestructive is true, and the user must be asked first), which is actionable. But there is no explicit when-to-use guidance relative to alternatives like execute_api_request or plan_vander_checks. Usage is largely implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the active logical environment for this workspace session (session CURRENT_ENV, e.g. STAGING). Interpolation resolves {CURRENT_ENV}VAR from .env.mcp.local before generic VAR (prefix-first). Put all env secrets there (DEVELOP, STAGING_); YAML stays generic.
| Name | Required | Description | Default |
|---|---|---|---|
| environment | Yes | ||
| workspaceRoot | No | Optional when MCP_WORKSPACE_ROOT is set. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose non-obvious behavior: the setting is session-scoped, and it changes variable resolution to a prefix-first rule ({CURRENT_ENV}_VAR before generic VAR). What it omits is validation/error behavior for an unknown environment name and whether the setting persists beyond the session.
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 tight sentences, front-loaded with the core action and scope, followed by the resolution semantics and the secret-placement convention. No padding or repetition.
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 low-complexity two-parameter setter with no output schema and no annotations, the description covers purpose, scope, side effects on interpolation, and naming conventions. Remaining gaps (invalid-value handling, persistence) are minor for a tool of this size.
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 50%: workspaceRoot is documented in the schema, but the required 'environment' parameter has no schema description. The description partially compensates by giving example values (STAGING, DEVELOP_*, STAGING_*), but does not state whether accepted values are constrained or free-form.
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 and resource: 'Set the active logical environment for this workspace session', with a concrete example value (STAGING). It is clear in isolation, but never explicitly contrasts itself with the nearby sibling set_environment_variable, and its heavy focus on variable interpolation could blur that boundary.
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?
Usage is implied rather than stated: the description explains the consequence of setting the environment (prefix-first resolution of {CURRENT_ENV}_VAR) and tells the caller where secrets belong (DEVELOP_*/STAGING_* in .env.mcp.local), but gives no explicit when-to-use or when-not-to-use versus set_environment_variable or get_environment_variable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set a session variable for subsequent requests.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| value | Yes | ||
| workspaceRoot | No | Optional when MCP_WORKSPACE_ROOT is set. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses only that the value applies to subsequent requests; it omits overwrite behavior, whether the variable survives across sessions, auth requirements, and failure modes for a mutation tool.
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?
A single tight sentence with the key effect front-loaded and no wasted words. It is efficient, though brevity here comes partly at the cost of completeness.
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 mutation tool with no annotations, no output schema, and two undocumented required parameters, the description is too thin. An agent lacks the information needed to call it correctly or distinguish it from its sibling set_environment.
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 33% (only workspaceRoot is documented). The description says nothing about 'name' or 'value' semantics, formats, or constraints, so it does not compensate for the missing schema documentation.
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 and resource ('Set a session variable') and adds scope ('for subsequent requests'), so an agent knows it writes a mutable value. However, it gives no differentiation from the sibling 'set_environment', whose relationship to this tool is left to inference.
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 phrase 'for subsequent requests' hints that the effect is session-scoped, but there is no explicit when-to-use, when-not-to-use, or alternative (e.g. set_environment vs set_environment_variable). No prerequisite or ordering guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Summarize a canonical API YAML without returning the full definition. Use names_only for triage (optionally with fields to trim endpoint entries); use full only when needed.
| Name | Required | Description | Default |
|---|---|---|---|
| fields | No | When given (detailLevel names_only only), projects each `endpoints` item to these keys only (id/method/path/description). | |
| requestId | No | ||
| detailLevel | No | names_only | |
| workspaceRoot | No | ||
| definitionRelativePath | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry behavioral disclosure. It usefully states that the tool summarizes without returning the full definition, and that fields projects endpoint entries, but it omits permission needs, error behavior, workspace requirements, and an explicit read-only characterization.
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 dense sentences with no filler. The purpose comes first, followed immediately by mode-selection guidance, so the most important information is front-loaded.
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 five-parameter tool with no annotations, only 20% schema description coverage, and no output schema, the description is only partially complete. It covers the purpose and mode usage well but leaves required-path semantics, return shape details, and error behavior unexplained.
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 20%. The description adds meaning for detailLevel (names_only vs full) and fields projection, but it does not explain the required definitionRelativePath, requestId, or workspaceRoot, leaving three of five parameters undocumented in both schema and 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?
States a specific verb ('Summarize') and resource ('canonical API YAML'), and distinguishes itself from the sibling read_api_definition by noting it avoids returning the full definition. An agent can tell what this tool does and how it differs from reading the full definition.
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 says to use names_only for triage and full only when needed, and notes that fields can trim endpoint entries. However, 'when needed' is vague and it does not name a sibling alternative such as read_api_definition or explain when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Call this whenever the user addresses Vander by name ("hi Vander", "oi Vander", "Vander, review X") or asks for a VANDER review. Pass workspaceRoot. Returns the Vander persona brief and, when no endpoint was named, an onboarding: what this server is, the three pieces it needs (.mcp/api/ YAML, .env.mcp.local, the conversation), which of them this workspace already has, and what the user can ask for. Adopt the persona for the rest of the conversation and follow its working method. Sends no HTTP request.
| Name | Required | Description | Default |
|---|---|---|---|
| requestId | No | Endpoint id the user wants reviewed, if they named one. | |
| workspaceRoot | No | Absolute project path (optional when MCP_WORKSPACE_ROOT is set). Lets Vander greet the user with what the workspace actually contains. | |
| definitionRelativePath | No | Definition the user wants reviewed, if they named one. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and largely does so: it discloses 'Sends no HTTP request', enumerates what the return contains, and instructs the agent to adopt the persona and follow its working method afterward. It omits any auth/permission requirements or error behavior, keeping it from a 5.
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 trigger is front-loaded in the first clause with no preamble, and most sentences earn their place by specifying return contents and post-invocation behavior. It is a dense single block rather than tightly structured, but there is little outright waste.
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?
There is no output schema and no annotations, so the description must cover trigger, arguments, returns and post-conditions, and it does: it names the return payload and the persona-adoption follow-up. It stops short of covering failure modes or prerequisites, leaving a minor gap for a persona/bootstrap 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 coverage is 100%, so the baseline is 3; the description adds only light meaning beyond the schema, noting that requestId/definitionRelativePath apply 'when an endpoint was named' and that workspaceRoot is the path to pass. It does not clarify the interaction between these optional args beyond what the schema already documents.
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 verb-and-resource (summoning the Vander persona) and states exactly what it returns: the persona brief plus an onboarding of what the server is and what the workspace has. This is distinguishable from siblings like plan_vander_checks and run_vander_checks, which act on checks rather than establishing the persona itself.
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 gives an explicit trigger condition, quoting concrete user phrasings ('hi Vander', 'oi Vander', 'Vander, review X') and the 'asks for a VANDER review' case, which is unusually actionable. It does not, however, state when NOT to call it or route explicitly to alternatives such as plan_vander_checks, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create or update a canonical YAML under .mcp/api/ only. mergeMode replace_file (requires replaceDefinition) or append_endpoints (requires appendEndpoints). New file on append needs createIfMissing. Default dryRun true returns preview without writing; set dryRun false and confirm true to write (atomic replace + optional .bak backup). Endpoint ids must not collide on append.
| Name | Required | Description | Default |
|---|---|---|---|
| dryRun | No | ||
| confirm | No | ||
| mergeMode | Yes | ||
| workspaceRoot | No | Optional when MCP_WORKSPACE_ROOT is set. | |
| appendEndpoints | No | Endpoints to append. Each: id, method, path; optional description, headers, params, body | form, auth | digest_auth {username,password}, auth_dependency, auth_retry_on_401, capture {var: jsonPath}, assert {status, jsonPathExists, maxDurationMs, checks[]}, sse {textPath}. | |
| createIfMissing | No | ||
| replaceDefinition | No | Whole definition: version, service, base_url, variables, flows, evals, endpoints[] (same shape as appendEndpoints items). | |
| targetRelativePath | Yes | Path under workspace, must be under .mcp/api/, e.g. .mcp/api/weather/staging.yaml |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so well: it discloses that writes are previewed by default (dryRun true returns `preview`), that a write requires both dryRun=false and confirm=true, that the replace is atomic with an optional .bak backup, and that endpoint ids must not collide on append. These are exactly the safety/mutation traits 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Dense and front-loaded: the core action leads, followed by mode requirements and then the write-safety workflow. Telegraphic but every clause conveys a distinct constraint; nothing is wasted.
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 an 8-parameter mutation tool with nested objects and no output schema, the description covers the write semantics and mode conditions thoroughly. Minor gaps remain around the shape of the `preview` return and workspaceRoot fallback, but the essentials for correct invocation are present.
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?
At 50% schema coverage, the description adds real conditional meaning beyond the schema: replace_file requires replaceDefinition, append_endpoints requires appendEndpoints, and a missing file on append requires createIfMissing. This cross-parameter dependency mapping is the key value-add, though targetRelativePath and workspaceRoot are left to the schema.
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 ('Create or update a canonical YAML') and bounds it to `.mcp/api/`, which is precise enough to separate it from read/list siblings. It does not, however, name or distinguish itself from the other definition-writing siblings like convert_legacy_to_canonical or import_curl.
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 strong operational guidance for how to use the tool (which mergeMode requires which payload, the dryRun/confirm workflow), but it never states when to reach for this tool versus the sibling converters/importers. Usage is implied by the create/update scope rather than contrasted with alternatives.
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.0assert_responseconvert_legacy_to_canonicaldiscover_legacy_api_sourcesdry_run_requestexecute_api_flowexecute_api_requestexplain_request_contextget_environment_variableimport_curlinit_workspacelist_api_definitionsplan_vander_checksread_api_definitionreorganize_mcp_api_definitionsrun_evalrun_vander_checksset_environmentset_environment_variablesummarize_api_definitionsummon_vanderupsert_canonical_api_definitionScored across 21 tools
Most tools target distinct actions (list vs read vs summarize, plan vs run VANDER checks, single request vs flow vs eval). A few pairs overlap in purpose—read_api_definition vs summarize_api_definition, convert_legacy_to_canonical vs import_curl—but descriptions provide clear guidance on when to use each.
Nearly all names follow a snake_case verb_noun pattern (execute_api_request, plan_vander_checks, set_environment_variable). Minor deviations such as set_environment vs set_environment_variable and the whimsical summon_vander keep it from being perfectly uniform, but the convention is still predictable.
21 tools is heavy for the domain; the server covers definition management, legacy conversion, execution, evals, VANDER checks, environment handling, and workspace init. Several pairs could arguably be merged (read/summarize, plan/run VANDER), making the count borderline rather than well-scoped.
The surface covers create/read/update via upsert, list, summarize, legacy conversion, request execution, assertions, flows, evals, VANDER checks, environment variables, and workspace init. A notable gap is an explicit delete tool for definitions or endpoints; upsert with replace_file can overwrite but does not obviously delete.
AI-callable tools for API mocking, testing, monitoring, security, and automation.
End-to-end API testing — generate and run tests from OpenAPI, curl, Postman, or real user traffic.
Give your AI hands. Identity, credential vault, and API gateway for autonomous agents.
Credential broker for AI agents: scoped, revocable API access with policy enforcement and audit.
