Every capture on this page is from 8 Aug 2026, from Claude Code —
payloads verbatim.

## 1 · The research question

*"Where's the tarball for hono, and how big is it unpacked?"* The npm
registry knows — but the agent has never seen this API's shape.

## 2 · The ordinary cost — the whole document, to learn two field names

Without a shape, discovery means pulling the full body into context just to
see what exists. Here that's **19,877 bytes (~5k tokens)** — measured with a
capped probe (`[truncated at max_bytes=300 of 19877]`); on a bigger API it's
[a megabyte](/search/examples/oversized-source.md).

## 3 · Discover the shape

```
fetch("https://registry.npmjs.org/hono/latest", schema: true)

{ "name": "string",
  "version": "string",
  "dist": { "tarball": "string", "unpackedSize": "number",
    "signatures[]": { "$items": 1, "sig": "string", "keyid": "string" } },
  "maintainers[]": { "$items": 1, "name": "string", "email": "string" },
  "keywords[]": "string (15 items)",
  "devDependencies": { "...": "string" } }
```

Arrays are sampled (first 20 elements, keys merged), so a field present in
only some rows still shows.

## 4 · Extract — paths copied straight from the schema

```
fetch("https://registry.npmjs.org/hono/latest",
      select: ["name", "version", "dist.tarball",
               "dist.unpackedSize", "maintainers[].name"])

{ "name": "hono", "version": "4.13.1",
  "dist": { "tarball": "https://registry.npmjs.org/hono/-/hono-4.13.1.tgz",
    "unpackedSize": 1376876 },
  "maintainers": [ { "name": "yusukebe" } ] }
```

Schema keys are `select` paths — copy-paste, no translation. When both are
passed, `schema` wins (it exists to discover the paths); a non-JSON body
answers `[schema ignored — body is not JSON]` with the capped body, never a
silent full dump.

## 5 · The answer the agent can now give

> hono 4.13.1 — tarball at
> `registry.npmjs.org/hono/-/hono-4.13.1.tgz`, **1,376,876 bytes unpacked**
> (~1.4 MB); maintained by yusukebe.
>
> Source: registry.npmjs.org/hono/latest, read 8 Aug 2026 `[via direct]` —
> ~0.2 KB of a 19.9 KB document reached the agent, paths straight from the
> schema.

## 6 · The same switch on markdown

One switch, two shapes: the server picks by what the body actually is. A
markdown or text body answers with its heading outline — exactly what
markdown `select` targets:

```
fetch("https://raw.githubusercontent.com/denoland/deno/main/README.md",
      schema: true)

[via direct][schema: markdown outline — 6 headings, 3815 bytes]
# Deno
## Installation
### Build and install from source
## Your first Deno program
## Additional resources
## Contributing
```

## 7 · Extract the section — whole, verbatim

Markdown `select` entries are content patterns, not paths — any section
containing the pattern returns whole, from cache:

```
fetch("https://raw.githubusercontent.com/denoland/deno/main/README.md",
      select: ["installation"])

## Installation
… the whole section — every install command, verbatim — and nothing else …
```

A miss returns the outline so the agent can re-aim; a text body with no
headings answers `[schema: no headings in N-byte text body]` with the capped
body.

## 8 · Measured improvement, and where this came from

Discovery plus extraction cost **under 1 KB** of context against the
19.9 KB document — and the second call never touched the origin. Fields
from JSON, sections from markdown, one call shape.

- **Client:** Claude Code over MCP
- **Captured:** 8 Aug 2026 — schema, select, outline and section calls,
  payloads verbatim
- **Measured:** full document 19,877 bytes, via capped probe
- **Retention:** body cached server-side, 24 h — both select calls reused it

## Run it yourself

[Install Search](/search#install) and ask an API you've never seen for its
shape — or start from [the same trick at 1.26 MB](/search/examples/oversized-source.md).