Choosing the Right Granularity for an Agent's Tools — Bundle or Split?

Three failures that tools-too-fine cause

Let me lay out why overly fine tools are dangerous, as the three failures I actually walked into.

The first is that the round trips bloat the context. Every tool call piles its input and output onto the conversation. Doing reads and writes as separate tools across five mediation groups is ten round trips on its own, and the context balloons fast. In my operation, the same task consumed roughly 40% fewer tokens after I bundled the tools than before.

The second is that the agent gets "lost" mid-procedure. It means to read with getEcpmFloor and then call setEcpmFloor, but slips a listMediationGroups for a different group in between, and which value it meant to write back where goes fuzzy. What a human holds as one continuous task, the agent is reassembling from memory at every tool boundary.

The third is that partially broken states tend to linger. Split the work of aligning floors across three networks into three writes, and when the second one fails you are left with one changed and two stale — a half-finished state. Fold it into one tool handled transactionally, and you get all-or-nothing.

The code below is the overly fine tool definition I wrote first.

// Before: UI operations copied straight into tools (too fine)
const tools = [
  {
    name: "get_ecpm_floor",
    description: "Get the current eCPM floor for the specified ad unit",
    parameters: {
      type: "object",
      properties: { adUnitId: { type: "string" } },
      required: ["adUnitId"],
    },
  },
  {
    name: "set_ecpm_floor",
    description: "Set the eCPM floor on the specified ad unit",
    parameters: {
      type: "object",
      properties: {
        adUnitId: { type: "string" },
        network: { type: "string" },
        floor: { type: "number" },
      },
      required: ["adUnitId", "network", "floor"],
    },
  },
];

With this design, to serve the single intent of "align the floors" the agent calls get_ecpm_floor, interprets the return, and repeats set_ecpm_floor once per network. The intent is one; the calls are split many ways.

What tools-too-coarse take away: the room to stop

So should you bundle everything? No. Push granularity too coarse and you erase the room for a human to intervene.

When I built the all-purpose optimizeMediation tool, the agent did indeed do everything in one call. But inside it, operations of completely different character — "lower a floor," "enable a new network," "disable an old group" — were executed all at once. Fine-tuning a floor can be redone any number of times; disabling a group hits revenue directly. Cram those into the same single call and the human loses the perfectly ordinary judgment of "approve only the floor tweak, hold the disable."

This is where reversibility enters. Operations you can undo and operations you cannot must not be handled at the same granularity. The only things safe to bundle coarsely are "operations of uniform character that can be redone freely." An operation whose results linger should be split off as its own tool — even if procedurally it sits right next to the others — to preserve a human decision point.

So granularity design runs on two axes at once: "bundle by intent" and "split by reversibility." Next I will show the middle shape that satisfies both.

The middle I settled on: one intent, one tool

What I finally settled on was bundling reads and writes by intent, while always showing the human "what it intends to do" through the return value.

// After: bundle by intent, disclose the plan in the return value
const tools = [
  {
    name: "align_ecpm_floors",
    description:
      "Align the eCPM floors of all networks on the given ad unit to a target. " +
      "Reads, diffs, and writes are executed as a single intent.",
    parameters: {
      type: "object",
      properties: {
        adUnitId: { type: "string" },
        targetFloor: { type: "number" },
        // dryRun=true returns the plan only and writes nothing
        dryRun: { type: "boolean", default: true },
      },
      required: ["adUnitId", "targetFloor"],
    },
  },
];
 
async function alignEcpmFloors(args: {
  adUnitId: string;
  targetFloor: number;
  dryRun: boolean;
}) {
  const current = await mediation.getFloors(args.adUnitId);
  // compute the diff within the same single decision
  const plan = current
    .filter((f) => Math.abs(f.floor - args.targetFloor) > 0.01)
    .map((f) => ({ network: f.network, from: f.floor, to: args.targetFloor }));
 
  if (args.dryRun || plan.length === 0) {
    // write nothing; return what it intends to do, structured
    return { applied: false, plan };
  }
  await mediation.applyFloors(args.adUnitId, plan);
  return { applied: true, plan };
}

To the agent, this tool resolves within one decision: "align the floors." The read and the diff are hidden inside, so it is one round trip and the context does not bloat. At the same time, because dryRun defaults to true, the first call always returns only a "plan." The agent presents that plan to the human, and applies it for real with dryRun: false only after approval.

The point is that bundling did not cost us the control point. The granularity got coarser, yet inserting the single dryRun step kept "the room to stop" intact. This is the middle I reached after swinging between both extremes.

Lower granularity on purpose — only for destructive actions

Bundling by intent is the baseline, but I keep exactly one exception. Only the destructive operations whose results linger do I deliberately split fine.

Disabling a mediation group, changing a billing plan, deleting production data — these "costly to undo" operations I carve into independent tools, even when procedurally they sit right next to others. And I always give those tools a confirmation step.

// Destructive ops: lower granularity on purpose, require a confirm token
const tools = [
  {
    name: "disable_mediation_group",
    description:
      "Disable a mediation group (destructive, affects revenue). " +
      "Call first without confirm, present the returned impact summary to the user, " +
      "and after approval call again with the confirmToken.",
    parameters: {
      type: "object",
      properties: {
        groupId: { type: "string" },
        confirmToken: { type: "string" },
      },
      required: ["groupId"],
    },
  },
];
 
async function disableMediationGroup(args: {
  groupId: string;
  confirmToken?: string;
}) {
  const impact = await mediation.estimateImpact(args.groupId);
  const token = makeConfirmToken(args.groupId, impact.revenueShare);
 
  if (args.confirmToken !== token) {
    // token mismatch = not yet approved
    return {
      applied: false,
      impact, // includes e.g. revenue share over the last 30 days
      confirmToken: token,
      message: "Review the impact of this disable and re-run with the same token after approval",
    };
  }
  await mediation.disableGroup(args.groupId);
  return { applied: true };
}

Here I am deliberately breaking the rule of bundling by intent. The call for confirmation and the call for execution are split into two on purpose. For a reversible operation, coarsening the granularity to cut round trips is correct; for an irreversible one, the correct move is the opposite — add one round trip if that is what it takes to physically interpose a human approval.

I suspect this asymmetry is not unrelated to both my grandfathers having been temple carpenters. Shaping wood can be adjusted endlessly, but a beam once cut off does not come back. So the discipline of "measure as often as you like, cut only once" is in their hands. Tool design for an agent is the same: adjust freely, cut carefully, and let granularity follow that.

The return value is half of granularity design

People tend to think granularity is about inputs (arguments), but I consider the shape of the return value to be the other half.

The agent reads the return value to make its next decision. So if the return is just "succeeded," the agent cannot tell what it can do next and ends up adding another call just to re-read the state. There goes the round trip you saved by bundling inputs — undone by a poor return.

What I aim for is to include, no more and no less, the information the agent needs for its next judgment in the return value. That is why align_ecpm_floors returns plan and disable_mediation_group returns impact. From the return alone the agent can assemble "what to show the user next and what to ask."

The opposite — stuffing internal IDs and raw debug data into the return — is also forbidden. The agent pulls all of it into context, and the noise dulls its judgment. The return value should carry only what the next move needs, in a structured form. Like the input, I trim it against the same yardstick: one decision.

The numbers, and what to do next

After folding this granularity rework into the mediation operation across six apps, several measurable things changed. For the same task of "align the floors on every ad unit," tool calls dropped from an average of eleven to three, and token consumption fell by roughly 40% by feel. The accidents where the agent lost its place mid-procedure and left a half-finished state — two or three a month — went essentially to zero once dryRun became the default. With destructive actions behind a confirm token, I no longer discover an "I didn't want that disabled" after the fact.

Bigger than the numbers was how much calmer the agent's behavior looked. Back when I handed it fine-grained tools, it always seemed to be checking something one line at a time. After bundling by intent, it executes one decision in one call and stops only when it needs to. That a single change in tool granularity makes the same model look so different was, honestly, a surprise.

If you are designing the tools you will hand your own agent right now, start by reviewing your current tool list through one question: "Is this one decision for the agent?" Where two or more decisions are packed into one tool, split them; where one decision is cleaved across several tools, bundle them. And for the operations you cannot undo, break that rule on purpose and interpose a confirmation step. That single pass of review is probably the highest-leverage improvement you can make.

Thank you for reading to the end. I hope it helps the design work of others who, like me, are running a lot on their own.