Skip to main content
Glama

Your agent just burned 12K tokens on a 200KB JSON response — to read one field. With mcp-peek: ~250 tokens for the same field. Same call, ~50× less context. See a live demo.

mcp-peek is an MCP server that wraps arbitrary REST API calls so your agent first sees a compact schema, then pulls only what it asked for through a jq mask. Big responses stay out of context until you actually need a slice — and every response carries next_step_hints plus structured error envelopes, so the agent self-corrects instead of guessing.

Use it in

Drop the snippet for your client into its MCP config. The desktop / IDE clients all spawn npx -y mcp-peek under the hood; the wrapping JSON differs slightly per client. Docker is an alternative wrapper for any of them — see the last entry.

{
  "mcpServers": {
    "mcp-peek": {
      "command": "npx",
      "args": ["-y", "mcp-peek"]
    }
  }
}

Config file lives at ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows). Restart Claude Desktop after editing.

claude mcp add mcp-peek -- npx -y mcp-peek

Or edit ~/.claude.json (user scope) / .mcp.json (project scope) directly with the same mcpServers shape as Claude Desktop.

{
  "servers": {
    "mcp-peek": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-peek"]
    }
  }
}

VS Code uses servers (not mcpServers) and requires type. Workspace-scoped — commit it for your team.

{
  "mcpServers": {
    "mcp-peek": {
      "command": "npx",
      "args": ["-y", "mcp-peek"]
    }
  }
}
{
  "mcpServers": {
    "mcp-peek": {
      "command": "npx",
      "args": ["-y", "mcp-peek"]
    }
  }
}

Cline stores this in cline_mcp_settings.json (open from the Cline panel → MCP Servers → Configure).

{
  "mcpServers": {
    "mcp-peek": {
      "command": "npx",
      "args": ["-y", "mcp-peek"]
    }
  }
}
{
  "mcpServers": {
    "mcp-peek": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        // Same-path bind mount + PEEK_FILES_ROOT: the agent passes
        // ordinary host paths under /home/me/data and they "just work"
        // inside the container. Outside-the-root paths are rejected
        // with a clear `invalid_input` error.
        "-v", "/home/me/data:/home/me/data",
        "-e", "PEEK_FILES_ROOT=/home/me/data",
        "ghcr.io/ed-smartass/mcp-peek:latest"
      ]
    }
  }
}

The same-path bind mount is the recommended Docker pattern — agent paths translate transparently. Drop PEEK_FILES_ROOT if you want no path constraint (and you're sure about the security tradeoffs).

Related MCP server: JSONShelf

What you get

  • http_request runs the call, caches the body, returns the structure, not the bytes.

  • http_read pulls fields out of the cached body via jq.

  • http_inspect re-renders the schema in another format — no second HTTP call.

  • server_info debug helper — version, runtime, effective env limits.

One MCP install replaces every curl your agent would run, so you authorize once at config time instead of approving each call.

Built for the agent

mcp-peek is shaped around how an agent actually reads an API, not how a human runs curl. Four structural choices follow from that:

  • Schema-first responses. http_request returns the shape of the body, not the body itself. The agent learns what's in there without burning tokens on bytes it will throw away.

  • next_step_hints on every response. JSON responses come back with advisory jq masks inferred from the top-level shape — the agent has a starting point instead of guessing field paths.

  • Structured error envelopes. Every failure is a typed error.kind with message and detail.hint. The agent branches programmatically on cause and acts on the hint, instead of parsing a stack trace.

  • Re-read instead of re-fetch. A cache_id lets the agent inspect the same body in another schema format, or extract a different slice, without a second HTTP call.

The agent-side consequences:

  1. ~50× less context on real-world payloads (see savings table below).

  2. One permission grant at install time, not per-call prompts.

  3. A self-correcting loop — typed errors and hints keep the agent from spiralling on guesses.

The rest of this README describes the operational surface; the design above is what makes that surface worth using.

Run modes & file paths

Which mode to pick

Mode

Pick when

Trade-offs

npx (default)

The MCP server runs on the same machine as your agent.

Simplest setup. Paths are local to your host — what the agent passes is what the server sees.

Docker

You want isolation, or are running the server alongside other tooling in containers.

Paths are local to the container. Use the same-path bind mount + PEEK_FILES_ROOT pattern (above) so agent paths "just work" without translation.

Remote MCP (over HTTP / SSE)

The server runs on shared infrastructure separate from the agent.

Surprising default: any path you pass for multipart.files.<name>.path, download_to, or save_to resolves on the server, not the agent's filesystem. For uploads, pass multipart.files.<name>.content_base64 instead (since v0.2) — the bytes travel inline in the JSON-RPC frame, no path semantics involved. Downloads still don't have an inline-base64 mode; keep download_to to npx/Docker.

Where do file paths resolve?

Field

npx

Docker

Remote MCP

multipart.files.<name>.path

host (agent's)

container — use same-path mount

server's filesystem

download_to

host (agent's)

container — use same-path mount

server's filesystem

save_to (in http_read)

host (agent's)

container — use same-path mount

server's filesystem

When PEEK_FILES_ROOT is set, all three are also constrained to that root (canonicalised — .. traversal cannot escape).

Multipart compatibility

Multipart uploads stream files via chunked transfer encoding (no Content-Length header). Most modern HTTP servers handle this fine. If you hit a server that rejects chunked uploads — typically primitive test servers or some legacy reverse proxies — file an issue with the response body, and we'll consider a non-chunked fallback in v0.3.

Tools

The four tools below are what the agent calls — you don't run them by hand. Examples show the agent's call sequence, not a CLI invocation.

Default flow: the agent calls http_request to get a schema + cache_id, then http_read with a jq mask to extract just the field(s) it needs. Keeps the agent's context small even on multi-MB responses. Setting body_mode: "inline" is rarely the right call — see body modes for cost framing.

Tool

What it does

http_request

Run an HTTP request; return a schema (and optionally a preview / full body, governed by body_mode). The body is cached for http_read, except when download_to streams it straight to disk.

http_read

Read a cached body, optionally filtered by a jq mask. Required for binaries (use save_to).

http_inspect

Re-render the cached body's schema in another format — no second HTTP call.

server_info

Debug helper. No params. Returns version, runtime, PEEK_FILES_ROOT, and every effective limit.

Body modes

http_request returns a schema by default. The body_mode parameter controls how much (if any) of the actual body comes back inline:

Mode

Returns

When the agent picks it

schema

schema only

The agent will follow up with http_read + a jq mask.

head

schema + body_preview (arrays/strings truncated, _truncated markers)

A quick peek to decide what to extract next.

inline

schema + the full body

The response is known-small and every field is needed. Capped by PEEK_INLINE_BODY_CAP (256 KB default).

auto (default)

server picks based on byte thresholds

Inline under PEEK_INLINE_THRESHOLD_BYTES (8 KB), head up to PEEK_HEAD_PREVIEW_THRESHOLD (64 KB), schema beyond that.

The actual mode picked, and the thresholds in effect, come back on every response in meta.body_inclusion so the agent can introspect what auto resolved to. JSON responses also get next_step_hints — advisory jq mask suggestions inferred from the top-level shape.

Debugging unexpected behaviour: server_info

When a path is rejected with invalid_input, or a tool behaves differently than you'd expect (Docker vs. host mode, a stale env var, the wrong version), call server_info first. It returns:

{
  "version": "0.3.0",
  "runtime": "docker" /* or "npx" / "unknown" */,
  "cwd": "/app",
  "files_root": "/home/me/data",          // null if PEEK_FILES_ROOT is unset
  "effective_limits": {
    "default_timeout_ms": 30000,
    "max_response_bytes": 52428800,
    "inline_threshold_bytes": 8192,
    "head_preview_threshold_bytes": 65536,
    "inline_body_cap_bytes": 262144,
    "max_inline_file_bytes": 10485760,
    /* …10 more fields… */
  }
}

No params. Cheap to call. Beats guessing why a path rejection said "/home/me/data" when you swore you set PEEK_FILES_ROOT=/data.

Schema formats

The same /users endpoint, four ways:

paths (default) — flat path listing, type + one example per leaf:

data[].id            : int    (e.g. 42)
data[].name          : string (e.g. "alice")
data[].roles[]       : string (e.g. "admin")
data[].profile.bio   : string|null
meta.total           : int    (e.g. 1247)
meta.next_cursor     : string|null

# 187 KB · data[]: 50 items

shape — TypeScript-like tree, more compact for deep data:

{
  data: [{
    id: int, name: string, roles: string[], profile: { bio: string|null }
  }] (50 items),
  meta: { total: int, next_cursor: string|null }
}
# 187 KB

sample — first item kept verbatim, rest collapsed; long strings auto-truncated:

{
  "data": [
    { "id": 42, "name": "alice", "roles": ["admin"], "created_at": "2026-05-09T..." },
    "...49 more"
  ],
  "meta": { "total": 1247, "next_cursor": "abc123" }
}

json_schema — standard JSON Schema (draft 2020-12), inferred via genson-js. Useful when feeding the schema back into a typed pipeline.

Pick the format that matches what the agent is doing: paths for "what fields exist", shape for "what's the structure", sample for "show me one realistic record", json_schema for downstream tooling.

jq cheatsheet

# Pick specific fields              .data | map({id, name})
# Drop heavy fields                 .data | map(del(.payload, .raw_html))
# Filter rows                       .data | map(select(.role == "admin"))
# Filter + pick                     .data | map(select(.active) | {id, email})
# First N                           .data[:5]
# Pluck single value                .meta.total
# Pagination cursor                 .meta.next_cursor // empty
# Group by                          .data | group_by(.tag) | map({tag: .[0].tag, n: length})
# Stats                             .data | length, (map(.score) | add / length)
# Errors only                       .results | map(select(.error))
# Flatten nested                    [.. | objects | select(.id?) | {id, type}]
# Search by substring               .items | map(select(.title | test("regex"; "i")))
# Sort + take top N                 .events | sort_by(.created_at) | reverse | .[:10]

output_mode: "all" (default) returns single-output filters as their value, multi-output filters as an array. output_mode: "first" collapses to the first emitted value.

Real-world examples

Each block below is what the agent does — a sequence of MCP tool calls in its loop. You don't type these.

1. Explore an unknown REST endpoint

The agent does:

http_request {method: "GET", url: "https://api.someservice.io/v1/widgets"}
  → schema (paths) shows what's there: data[].id, data[].name, meta.next_cursor, …
http_read {cache_id, mask: ".data | map({id, name})"}
  → just the slice the agent needs

2. Pull only id and created_at from GitHub issues

The agent does:

http_request {
  method: "GET",
  url: "https://api.github.com/repos/anthropics/claude-cookbooks/issues",
  headers: {accept: "application/vnd.github+json"}
}
http_read {cache_id, mask: ".[] | {id, created_at}"}

3. Upload an image via multipart

The agent does:

http_request {
  method: "POST",
  url: "https://upload.example.com/photos",
  headers: {authorization: "Bearer …"},
  multipart: { files: { photo: { path: "/host/photo.jpg", content_type: "image/jpeg" } } }
}

For remote-MCP setups (or any time a server-side path makes no sense), use the inline variant — bytes travel in the JSON-RPC frame, no PEEK_FILES_ROOT constraint applies:

http_request {
  method: "POST",
  url: "https://upload.example.com/photos",
  multipart: { files: { photo: {
    content_base64: "<base64 bytes>",
    filename: "photo.jpg",
    content_type: "image/jpeg"
  } } }
}

Inline payloads are capped at PEEK_MAX_INLINE_FILE_BYTES (10 MB pre-base64 by default).

4. Stream a binary download to disk

The agent does:

http_request {
  method: "GET",
  url: "https://example.com/big.zip",
  download_to: "/tmp/big.zip"
}
  → response is never buffered in agent context; sha256 + byte count returned

Configuration

All env vars are optional. Defaults match common-sense limits.

Env var

Default

Purpose

PEEK_DEFAULT_TIMEOUT_MS

30000

per-request HTTP timeout

PEEK_MAX_RESPONSE_BYTES

52428800

hard cap on cached body size (50 MB)

PEEK_CACHE_TTL_SECONDS

600

cache entry lifetime (10 min)

PEEK_INLINE_THRESHOLD_BYTES

8192

body_mode: "auto" upgrades to inline below this

PEEK_HEAD_PREVIEW_THRESHOLD

65536

body_mode: "auto" upgrades to head below this; otherwise schema

PEEK_HEAD_PREVIEW_ITEMS

5

array items kept verbatim in body_preview (rest collapsed)

PEEK_HEAD_PREVIEW_STRING

200

string truncation length in body_preview

PEEK_INLINE_BODY_CAP

262144

hard cap on body_mode: "inline" (256 KB)

PEEK_MAX_INLINE_FILE_BYTES

10485760

hard cap on multipart.files.<name>.content_base64 (10 MB pre-base64)

PEEK_JQ_TIMEOUT_MS

5000

per-mask jq timeout

PEEK_USE_NATIVE_JQ

0

switch to subprocess jq (reserved, not heavily exercised)

PEEK_TLS_INSECURE

0

skip TLS verification

PEEK_SCHEMA_MAX_DEPTH

10

recursion depth for schema renderers

PEEK_SCHEMA_MAX_OBJECT_KEYS

200

per-object key cap

PEEK_SCHEMA_SAMPLE_MAX_STRING

100

string truncation in samples

PEEK_FILES_ROOT

(unset)

restricts multipart.files.<name>.path, download_to, and save_to to canonical paths under this prefix; unset means no constraint. Does not apply to multipart.files.<name>.content_base64 (no path involved)

How much context does this actually save?

Approximate token costs for a single agent turn that wants one slice of a real-world API response. Tokenizer-dependent (Anthropic Claude tokens, English-heavy JSON, ~4 chars/token); your numbers will vary by ±30%.

Endpoint

Raw response

Raw tokens

Peek schema

Peek tokens

Savings

GitHub Issues — GET /repos/X/Y/issues (page of 30)

~200 KB

~12 000

~1 KB

~250

~48×

Stripe Charges — GET /v1/charges?limit=10

~80 KB

~5 000

~0.6 KB

~150

~33×

OpenWeather — GET /data/2.5/forecast (5 day / 3 h, 40 entries)

~30 KB

~2 000

~0.5 KB

~120

~17×

Once the agent has the schema, http_read {cache_id, mask: "..."} returns just the slice — typically a handful of tokens.

Compared to alternatives

mcp-peek

fetch-mcp

curl + jq

All HTTP methods

Custom headers

Multipart file uploads

Schema-first responses

Field filtering (jq)

manual

Doesn't dump 200KB into agent context

Single permission grant (no per-call prompt)

Structured errors + next_step_hints

License

MIT — see LICENSE.

Contributing

See CONTRIBUTING.md for branch naming, conventional-commit style, and the PR flow. Bug reports and feature ideas go in GitHub Issues.

Available Tools

4 tools
http_inspectA

Re-render the cached response schema in a different format (paths | shape | sample | json_schema) without making a second HTTP call. Try shape for nested structures, sample to see one realistic record, or json_schema for downstream typed pipelines.

ParametersJSON Schema
NameRequiredDescriptionDefault
cache_idYes
schema_formatYes

TDQS

A4/5.0
Behavior3/5

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

No annotations are provided, so the description must carry the burden. It discloses a key behavioral trait (no HTTP call), but lacks details on cache miss handling, permissions, or idempotency.

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

Conciseness5/5

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

Two sentences with no fluff. First sentence states purpose and options, second provides usage guidance. Information is front-loaded and every word earns its place.

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

Completeness4/5

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

Given the simple 2-param tool with no output schema, the description covers purpose, format options, and a behavioral trait. Missing context about cache_id source and error handling, but mostly complete.

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

Parameters3/5

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

Schema description coverage is 0%. The description adds context for schema_format with recommendations, but does not explain cache_id or how to obtain it. The enum values are listed in schema, so some value is added but incomplete.

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

Purpose5/5

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

The description clearly states the tool re-renders a cached response schema in different formats without a second HTTP call, using specific verbs and resource. It distinguishes from siblings like http_read and http_request by emphasizing cache inspection.

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

Usage Guidelines4/5

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

The description gives recommendations on when to use each format (e.g., 'Try `shape` for nested structures'), but does not explicitly contrast with sibling tools or specify 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.

http_readA

Read a cached response body, optionally filtered through a jq mask. Tip: lead with length (e.g. mask: ".data | length") to learn the size before listing items. Required for binary bodies — pass save_to to stream the body to disk; binaries are never inlined into your context.

ParametersJSON Schema
NameRequiredDescriptionDefault
cache_idYes
maskNojq expression; valid only for JSON bodies.
output_modeNoDefault 'all'.
save_toNoRequired for binary bodies.

TDQS

A4.2/5.0
Behavior4/5

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

Discloses key behaviors: binaries are never inlined, save_to is required for binary bodies, mask works only on JSON. Since no annotations are provided, the description carries full burden and does a good job of conveying important behavioral details beyond schema.

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

Conciseness5/5

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

Three sentences: first states core purpose, second gives a usage tip, third clarifies binary handling. Every sentence adds value; no fluff or repetition. Front-loaded effectively.

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

Completeness4/5

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

With 4 parameters, no output schema, and no annotations, the description sufficiently covers binary handling, mask scope, and caching context. Slightly lacking in explicitly stating it reads cached responses (implied), but otherwise complete for a read tool.

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

Parameters3/5

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

Schema coverage is high (75%). Description adds limited extra parameter meaning—mostly a tip for mask usage. Baseline of 3 is appropriate as schema already provides descriptions for mask, output_mode, and save_to. No mention of cache_id semantics beyond being required.

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

Purpose5/5

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

Description clearly states 'Read a cached response body, optionally filtered through a jq mask.' It specifies the verb 'read' and resource 'cached response body', and distinguishes from siblings like http_request (which makes requests) and http_inspect (likely inspects metadata) by focusing on cached data retrieval.

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

Usage Guidelines4/5

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

Provides actionable tips: leading with 'length' to learn size, requiring save_to for binary bodies, and noting mask validity only for JSON. Missing explicit when-not-to-use or alternatives to siblings, but the guidance is clear and context-aware.

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

http_requestA

Perform an HTTP request and return a compact schema of the response, not the full body.

Default flow (use this for any non-trivial response): (1) call http_request to get { schema, cache_id }; (2) call http_read with cache_id and a jq mask to extract only the field(s) you need. This keeps your context small even on multi-MB responses.

body_mode controls how much of the body comes back inline: schema (no body — schema only) head (schema + truncated preview of arrays/strings — middle ground) inline (schema + full body — costly; capped by PEEK_INLINE_BODY_CAP) auto (default — server picks based on byte thresholds) Reach for inline ONLY when body is known-small AND every field is needed; a 200KB JSON inlined is ~12K tokens of context for data you may never use.

Multipart uploads stream files via chunked transfer encoding (no Content-Length). Most servers accept this; some legacy proxies / primitive test servers reject it.

Cookbook: • Explore an unknown endpoint: http_request {method: "GET", url} → schema shows what is there http_read {cache_id, mask: ".data | map({id, name})"} • Top 10 GitHub issues by comment count: http_request {method: "GET", url: "https://api.github.com/repos/OWNER/REPO/issues"} http_read {cache_id, mask: "sort_by(-.comments)[:10] | .[] | {id, title, comments}"}

ParametersJSON Schema
NameRequiredDescriptionDefault
methodYes
urlYesAbsolute URL.
queryNo
headersNo
bodyNoObject → JSON; string → text/plain; mutually exclusive with body_raw and multipart.
body_rawNoRaw payload; pair with content_type.
multipartNo
content_typeNoOverride Content-Type.
timeout_msNoDefault 30000.
follow_redirectsNoDefault true (max 10 hops).
tls_insecureNoDefault false.
schema_formatNoDefault 'paths'.
body_modeNoDefault 'auto'. schema | head | inline | auto.
download_toNoStream body to file (skips cache).

TDQS

A4.7/5.0
Behavior5/5

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

No annotations provided, but the description fully covers behavior: returns schema and cache_id by default, body_mode controls body inclusion, multipart uses chunked encoding (may fail on legacy proxies). It does not contradict annotations (none provided).

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

Conciseness4/5

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

Well-structured and front-loaded with key information, but slightly lengthy. However, every sentence serves a purpose, and the cookbook adds practical value without being verbose.

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

Completeness4/5

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

Given the tool's complexity (14 parameters, nested objects, no output schema), the description covers essential usage patterns, workflow, and caveats. Could mention error handling or authentication, but overall adequate.

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

Parameters4/5

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

Schema description coverage is 71%, so baseline is 3. The description adds significant value by explaining body_mode in detail and the overall request flow, going beyond schema descriptions.

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

Purpose5/5

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

The description clearly states the tool performs HTTP requests and returns a compact schema of the response, not the full body. It distinguishes itself from siblings http_read and http_inspect by explaining the two-step workflow.

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

Usage Guidelines5/5

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

Explicitly describes the default two-step flow and provides a cookbook with specific examples. It also advises when to use body_mode options sparingly, especially inline mode, and notes multipart streaming constraints.

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

server_infoA

Debug helper. No params. Returns the current mcp-peek version, runtime detection (npx | docker | unknown), cwd, files_root (PEEK_FILES_ROOT, or null when unset), and an effective_limits object summarising every configured cap / threshold / timeout (15 fields — see README for the full list). Use when a path is rejected unexpectedly, or to confirm which container/host the server is actually running in.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.7/5.0
Behavior5/5

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

With no annotations provided, the description fully discloses the tool's behavior: it is a read-only debug helper with no side effects, returning specific fields. It explains exactly what is returned and notes reference to README for full list, leaving no ambiguity.

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

Conciseness5/5

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

The description is concise (5 sentences) and front-loaded with 'Debug helper. No params.' It efficiently communicates purpose, return values, and usage, with no wasted words.

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

Completeness5/5

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

Given no parameters, no output schema, and low complexity, the description is complete. It lists all return fields and directs to README for the full effective_limits list, which is sufficient for an agent to understand and invoke the tool correctly.

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

Parameters4/5

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

There are no parameters, and schema description coverage is 100%. The description adds no param details because none are needed, but the baseline score of 4 is appropriate for a zero-parameter tool.

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

Purpose5/5

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

The description clearly states it is a 'debug helper' that returns server information such as version, runtime detection, cwd, files_root, and effective_limits. It distinguishes itself from sibling tools (http_inspect, http_read, http_request) which are HTTP-related, so the agent knows this is the only info/debug tool.

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

Usage Guidelines4/5

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

The description provides explicit usage scenarios: 'Use when a path is rejected unexpectedly, or to confirm which container/host the server is actually running in.' This gives clear context, though it doesn't mention when not to use the tool, which would be helpful but not essential.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv0.3.0
    • First observedhttp_inspect
    • First observedhttp_read
    • First observedhttp_request
    • First observedserver_info

TDQS

A4.4/5.0

Scored across 4 tools

Disambiguation5/5

Each tool targets a distinct action: http_request makes a request and returns schema, http_read reads cached body with jq masking, http_inspect re-renders cached schema in different formats, and server_info provides debug metadata. No overlap.

Naming Consistency5/5

All tool names follow a consistent lowercase_underscore pattern (http_inspect, http_read, http_request, server_info), making them predictable and easy to distinguish.

Tool Count5/5

Four tools is well-scoped for a server focused on HTTP inspection and caching. Each tool earns its place, covering the core workflow without unnecessary bloat or gaps.

Completeness5/5

The tool set covers the full intended workflow: make a request, inspect schema, read cached body with jq filtering, re-render in alternative formats, and debug server state. Minor cache management features are absent but not essential for the server's stated purpose.

Maintenance

ActivitySlowing
ResponsivenessSyncing

Related MCP Connectors

Related MCP Servers