Cutting MCP Tools Didn't Make Anything Lighter — 2,377 Bytes of Definitions vs 110,298 Bytes of Response

The response side was where everything lived

Next I called tools/call and measured the returned text.

All twelve tool definitions together — 2,377 bytes — amount to 2.2% of a single large response.

Narrowing the returned fields to id, title, and category took 110,298 bytes down to 19,659. That is an 82.2% reduction, against the roughly 1.2 KB I saved by halving the tool count. Two orders of magnitude apart.

This was the part that genuinely surprised me. "Too many tools makes it heavy" is a claim I had read often enough to stop questioning. Measured, definitions behave like a fixed cost that stays small, and the entire variable cost sits in the response.

I also timed 500 round trips while I had the harness open. A single-record get_wallpaper call came back at p50 = 0.21 ms, p95 = 0.27 ms, p99 = 0.35 ms, with a maximum of 0.67 ms. Locally, the stdio round trip is not the constraint. When something feels slow, the transport is the wrong suspect — the payload is the right one.

Summed across a session, the gap widens further

initialize and tools/list run once at the start of a session. tools/call runs repeatedly for as long as the work lasts.

Taking the measured values and summing a session of twenty calls:

Projection alone takes the session total from 444,677 bytes to 81,257 — an 81.7% reduction.

In neither configuration do the definitions exceed 3% of the total. The more calls a session makes, the smaller that share becomes.

Put the projection in the contract, not in the return statement

My first fix was a map right before returning. It works.

The trouble is that from the caller's side, the tool still looks like something that might hand back every field. When a future version of me reuses list_wallpapers for a different purpose, 110 KB comes back silently.

So I moved the projection into the tool's description: "returns only id, title, and category." Written there, it stops being an implementation detail and becomes a contract. It also settles the division of labour — when you need every field, you fetch one record through get_wallpaper.

Slicing on a byte boundary breaks every time

The obvious way to cap a response is to truncate the JSON string at N bytes.

I wanted to know how bad that actually is. Taking the full 110,298-byte JSON string, I cut it at every 100-byte step from 1,000 to 19,000 and fed each result to JSON.parse.

Of 181 cut positions, 181 failed. 100.0%.

In hindsight it could hardly be otherwise. Cut inside an array and the bracket never closes. Cut inside a string and neither does the quote. A lucky landing on a clean boundary is theoretically possible, and across 324 records it never happened once.

Cut on record boundaries instead. Fix the byte budget first, then add records until the next one would overflow.

// Slice a page out of a byte budget. Boundaries are always whole records.
const byteLen = (v) => Buffer.byteLength(JSON.stringify(v), "utf8");
 
function pageByByteBudget(rows, budget, offset = 0) {
  const out = [];
  let bytes = 2;                      // Account for the "[]" of an empty array up front
  let i = offset;
 
  for (; i < rows.length; i++) {
    const add = byteLen(rows[i]) + (out.length ? 1 : 0);  // Don't forget the separating comma
    if (bytes + add > budget) break;
    out.push(rows[i]);
    bytes += add;
  }
 
  // Not even one record fits. Fail loudly here, or the caller loops forever.
  if (out.length === 0 && i < rows.length) {
    throw new Error(
      `record at ${i} exceeds budget: ${byteLen(rows[i])}B > ${budget}B. ` +
      `Project more aggressively, or raise the budget.`
    );
  }
 
  return {
    rows: out,
    bytes: byteLen(out),
    nextOffset: i < rows.length ? i : null,   // null means the end
  };
}

That out.length === 0 branch was added afterwards. I had set a 2 KB budget while forgetting to project, so nothing fit, nextOffset never advanced, and the caller paged through the same position indefinitely. Anything that stalls quietly at a boundary condition takes a long time to trace back.

Measured across budgets:

Fill rates land between 99.3% and 100.0% — considerably more honest than hard-coding limit: 20 and hoping.

Having "136 records at 8 KB" written down also ends the debate about default values. I set the default limit to 50 and the ceiling to 136.

The reason to merge tools turned out to be legibility, not volume

By this point the case for reducing the tool count had evaporated. Each one costs 189 bytes.

I merged twelve into six anyway, for a completely different reason.

What had actually been bothering me was not size. It was how often the wrong tool got picked — a request that clearly meant list_wallpapers arriving at search_wallpapers.

That is measurable. Concatenate each tool's name and description, reduce it to a set of character bigrams, and the Jaccard coefficient tells you which pairs are hard to tell apart.

// Measure how hard tools are to tell apart: Jaccard over name+description bigrams
const bigrams = (s) => {
  const t = s.toLowerCase().replace(/[_\s]/g, "");
  const set = new Set();
  for (let i = 0; i < t.length - 1; i++) set.add(t.slice(i, i + 2));
  return set;
};
 
const jaccard = (a, b) => {
  let inter = 0;
  for (const x of a) if (b.has(x)) inter++;
  return inter / (a.size + b.size - inter);
};
 
function collisionReport(tools, threshold = 0.30) {
  const sets = tools.map((t) => bigrams(t.name + " " + t.description));
  const pairs = [];
  for (let i = 0; i < tools.length; i++) {
    for (let j = i + 1; j < tools.length; j++) {
      pairs.push({ a: tools[i].name, b: tools[j].name, score: jaccard(sets[i], sets[j]) });
    }
  }
  pairs.sort((x, y) => y.score - x.score);
  return {
    worst: pairs.slice(0, 5),
    over: pairs.filter((p) => p.score >= threshold),
    mean: pairs.reduce((s, p) => s + p.score, 0) / pairs.length,
  };
}

Run against the twelve:

Four of 66 pairs sat at or above 30%, with a mean of 13.1%.

The 45.5% at the top says that get_build_config and get_app_config share both a naming shape and a description shape. "Retrieves the build configuration" and "retrieves the app configuration" give no basis for choosing between them. A human reviewer hesitates there too.

The merge followed five rules:

1. Fold the three search-shaped tools into one query_wallpapers, moving category, tag, query, and limit into arguments
2. Collapse the two configuration tools into get_config, with a profile argument selecting which
3. Collapse the three i18n tools into i18n_report, returning coverage and missing keys in one response
4. Keep get_wallpaper as the single entry point for one record with every field
5. Include one sentence in every description stating what the tool does not return

Measuring the resulting six the same way gives a maximum of 17.0% and a mean of 9.4% — down from 45.5% and 13.1%.

The falling numbers matter less than what they revealed: the thing to reduce was overlap between descriptions, not the count. Halve the tools while leaving the wording similar and the mix-ups survive. Keep twelve tools that read distinctly and you are fine.

Merging too far creates a different problem

To be fair to the alternative, giving query_wallpapers four arguments is not free. The more argument combinations exist, the more room there is to be called with a combination nobody intended.

My rule is to cap a tool at four arguments and split it once a fifth is wanted — on the reasoning that a fifth argument usually signals a separate concern. There is no theory behind that threshold. It simply has not failed me yet.

A small harness for measuring your own server

Here is the measurement side of the code that produced these numbers. Point it at an existing MCP server by swapping the server.mjs path.

// bench.mjs — measure byte sizes and round trips for a local MCP server
//   run: node bench.mjs ./server.mjs
import { spawn } from "node:child_process";
import { createInterface } from "node:readline";
 
const target = process.argv[2] ?? "./server.mjs";
const child = spawn("node", [target], { stdio: ["pipe", "pipe", "inherit"] });
const rl = createInterface({ input: child.stdout });
 
const pending = new Map();
let id = 0;
rl.on("line", (line) => {
  const msg = JSON.parse(line);
  const resolve = pending.get(msg.id);
  if (resolve) { pending.delete(msg.id); resolve(msg); }
});
 
const rpc = (method, params) =>
  new Promise((resolve) => {
    const i = ++id;
    pending.set(i, resolve);
    child.stdin.write(JSON.stringify({ jsonrpc: "2.0", id: i, method, params }) + "\n");
  });
 
const B = (v) => Buffer.byteLength(JSON.stringify(v), "utf8");
 
await rpc("initialize", {});
 
// (1) Cost of the definition side
const list = await rpc("tools/list", {});
console.log(`tools/list: ${B(list.result)} bytes / ${list.result.tools.length} tools`);
 
// (2) Cost of the response side — pick the call most likely to be large
const call = await rpc("tools/call", { name: "list_wallpapers", arguments: {} });
const respBytes = Buffer.byteLength(call.result.content[0].text, "utf8");
console.log(`tools/call: ${respBytes} bytes`);
console.log(`ratio: response is ${(respBytes / B(list.result)).toFixed(1)}x the definitions`);
 
// (3) Round trip time — confirm whether the transport is the constraint
const samples = [];
for (let i = 0; i < 200; i++) {
  const t0 = process.hrtime.bigint();
  await rpc("tools/call", { name: "list_categories", arguments: {} });
  samples.push(Number(process.hrtime.bigint() - t0) / 1e6);
}
samples.sort((a, b) => a - b);
console.log(`round trip p50=${samples[100].toFixed(2)}ms p95=${samples[190].toFixed(2)}ms`);
 
child.kill();

The id matching inside rl.on("line") is not optional. JSON-RPC makes no ordering guarantee, so responses have to be paired back to requests by id — skip it and you will eventually read someone else's answer.

If the ratio line comes back as a two-digit number, you are looking at the same situation described here. Start on the response side.

Three rules I now follow

1. Ignore the tool count. A fixed cost of roughly 189 bytes per tool is negligible against the variable cost of responses
2. Constrain every response with projection and a byte budget. State the returned fields in the description, and route output through a record-boundary paginator
3. Measure description similarity before merging. Any pair above 30% is a signal to merge or to rewrite

If you have an MCP server in front of you, two measurements are enough to start. Count the bytes of one tools/list response, and count the bytes of your largest tools/call response. If those numbers differ by two orders of magnitude, you already know which side to work on.

I spent half a day deleting tools on an assumption. The measurement takes about twenty lines.

For a related look at response size, A JSON File 19% Smaller That Ships Only 3% Smaller — Measuring Catalog Payloads Against gzip measures what survives compression, which is the other half of the same question.