OpenClaw Tool Layer Architecture: Designing the Tools Your Agents Call

An agent of mine once sent the same invoice reminder to a customer four times in eleven minutes. The model had not lost its mind. The email tool timed out after the provider accepted the message, returned an error string, and the agent did the sensible thing with an error string: it tried again. Three more timeouts, three more emails, and one very polite reply from the customer asking if we were okay.

I spent a day tuning the prompt before I looked at the tool.

The Tool Layer Is the Real Interface

People put enormous effort into system prompts and then hand the model a tool list that reads like a raw API dump. The model sees both. In a typical OpenClaw session the tool definitions take up more tokens than the persona does, and the model consults them on every single turn, so a vague parameter description costs you over and over again for as long as the agent runs.

Everything below assumes the plumbing already exists. The MCP orchestration guide covers how tools get registered and served, and the gateway handles routing. This article is about the shape of each tool, meaning what goes in and what comes back out.

Granularity: Design Around the Agent's Job

The most common mistake is wrapping every REST endpoint as its own tool. A CRM with forty endpoints becomes forty tools, and the agent now has to plan a five-call sequence (search contact, fetch contact, list deals, fetch deal, update stage) to do one thing a human would describe in a sentence. Each hop is another chance to pass the wrong ID.

Design tools around the tasks the agent performs. My rough test: if the agent calls tool A and then almost always calls tool B with a field from A's result, those two want to be one tool.

• Too fine: crm_get_contact, crm_list_deals_for_contact, crm_get_deal, crm_patch_deal.
• About right: crm_find_deal (search by company or contact name, returns the deal with its contact already attached) and crm_move_deal_stage.
• Too coarse: crm_do with a free-text instruction field. You have now built a second agent inside a tool, with none of the logging.

Tool count matters too, though less than people think. Past roughly twenty tools in one agent's list, I start seeing selection errors between similar names. Past forty, it gets bad enough that splitting the work across specialized agents with smaller toolsets beats any amount of description polishing.

Schemas the Model Reads Correctly

The schema is documentation, and the model is the only reader who matters. Write descriptions for someone smart who has never seen your system and cannot ask questions. Say when to reach for this tool instead of its neighbor. Then say what each field means, in the units your backend expects.

{
  name: "calendar_create_event",
  description:
    "Create an event on the owner's calendar. Use calendar_find_slots first " +
    "if the user has not given an exact time. Does NOT send invites; " +
    "use calendar_invite for that.",
  input_schema: {
    type: "object",
    properties: {
      title:      { type: "string", maxLength: 120 },
      start:      { type: "string", description: "ISO 8601 with offset, e.g. 2026-10-02T14:00:00-07:00" },
      duration_minutes: { type: "integer", minimum: 5, maximum: 480 },
      visibility: { type: "string", enum: ["busy", "private", "public"], default: "busy" },
      idempotency_key: { type: "string", description: "Reuse the same key when retrying this exact request." }
    },
    required: ["title", "start", "duration_minutes", "idempotency_key"]
  }
}

A few habits carry most of the weight here. Use enums wherever the backend accepts a closed set, since a model will invent "tentative" for a field that only accepts three values. Prefer duration_minutes over a second timestamp, because models are better at small integers than at date arithmetic across a timezone boundary. Name the units in the field name. And put the negative guidance ("does NOT send invites") right in the description, since that one line prevents a whole category of confused follow-up calls.

Keep IDs out of the model's hands where you can. If the agent has to copy a 24-character opaque string from one result into the next call, it will eventually drop a character. Let tools accept human-meaningful references (an email address, a company name plus a date) and resolve them server-side, returning a clear ambiguity error when two records match.

Side Effects Need Idempotency Keys

Back to the four invoice reminders. The fix was a required idempotency_key on every tool that changes the outside world. The agent generates the key once per intent. The tool layer records the key alongside the outcome before returning, and a second call with the same key returns the stored result without doing anything.

async function withIdempotency(ctx, tool, args, run) {
  const key = `${ctx.agentId}:${tool}:${args.idempotency_key}`;
  const prior = await ledger.get(key);
  if (prior?.status === "done") return { ...prior.result, replayed: true };
  if (prior?.status === "in_flight") return { status: "pending", retry_after_s: 30 };

  await ledger.put(key, { status: "in_flight", at: Date.now() });
  try {
    const result = await run(args);
    await ledger.put(key, { status: "done", result });
    return result;
  } catch (err) {
    // only clear the key if we know the side effect did not happen
    if (err.definitelyNotApplied) await ledger.delete(key);
    throw err;
  }
}

The in_flight branch is the part people skip, and it is exactly the case that bit me. A timeout does not tell you whether the email went out. Returning "pending, check back in thirty seconds" gives the agent an honest answer and something useful to do with it. Returning a generic error invites a retry.

Read-only tools can skip all of this. Split your tools into reads and writes early and put them in different registries if you can, because the approval gates want that same split.

Shape the Result for the Context Window

Whatever a tool returns goes straight into the context window, and stays there until compaction. A search tool that returns fifty full records at 400 tokens each has just spent 20,000 tokens of working memory on a question whose answer was probably in the first three rows. Do that a few times per session and the agent starts forgetting its own instructions.

Return a summary shape by default and a detail shape on request. Cap list results (ten is a sane default) and always say how many more exist, so the agent knows its view is partial. Strip fields the model has no use for, like audit metadata or the nested objects three levels deep that only exist for your frontend. The context window architecture piece covers budgeting in general. The tool layer is where most of that budget actually gets spent.

// what the agent sees from crm_find_deal
{
  "matches": 2,
  "shown": 2,
  "deals": [
    { "ref": "Northwind / Q4 renewal", "stage": "proposal", "value_usd": 18000,
      "contact": "Dana Ortiz <dana@northwind.example>", "last_touch_days_ago": 9 },
    { "ref": "Northwind / pilot expansion", "stage": "closed_lost", "value_usd": 6500,
      "contact": "Dana Ortiz <dana@northwind.example>", "last_touch_days_ago": 142 }
  ],
  "hint": "Two deals match 'Northwind'. Pass ref to crm_move_deal_stage."
}

That hint field tells the agent what a sensible next call looks like in the same breath as the data. Wandering drops noticeably.

Errors Are Instructions

An agent reads a tool error the way a new employee reads a note from their manager. Error: 422 teaches it nothing. start is in the past (2026-09-12). Did you mean 2026-10-12? fixes the problem on the next turn.

I sort every tool error into one of four buckets and return the bucket as a field, alongside a sentence the model can act on:

• invalid_input: the agent can fix it by changing arguments. Say which field and why.
• ambiguous: more than one thing matched. List the candidates in summary shape.
• transient: rate limit, timeout, provider hiccup. Include retry_after_s. The retry logic from the error handling guide should usually live in the tool layer so the agent never sees most of these at all.
• not_permitted: the agent must stop and escalate. The message should say so plainly ("do not retry; ask the owner"), because a model left to its own devices will look for a second tool that does the same thing.

Never return a stack trace. Models treat long technical text as a puzzle to solve, and they will happily spend four turns solving it.

A Word on Clever Tools

The day you catch yourself adding a tool whose job is to call other tools on the agent's behalf, go for a walk first.

Versioning and Deprecation

Tools change more often than prompts, and a changed tool silently changes agent behavior. Rename a field from due to due_date and every scheduled job whose prompt mentions "due" keeps working for a week, then fails at 6 a.m. on a Saturday when the old alias is removed.

Treat the tool manifest like a public API. Version it in the repo next to your prompts (the prompt versioning workflow applies almost unchanged), accept old field names for one release while returning a deprecated warning in the result, and run your evaluation suite against the new manifest before it ships. Agents do read those warnings. Some of them even adapt mid-session.

Failure Modes Worth Knowing

Testing Tools Against the Model

Unit tests confirm a tool works when called correctly. They say nothing about whether the model will call it correctly. For that you need a small eval set per tool: fifteen or twenty realistic requests, each with the tool call you expect, run against the actual model your agent uses.

Score two things. Did the agent pick the right tool, and were the arguments valid on the first try? When the second number drops after a schema change, the description got worse, whatever the diff looked like to you. Put the suite in CI and it becomes the cheapest regression signal you have.

Internal Links & Further Reading

To go deeper on the layers this article references:

• OpenClaw MCP Orchestration →

  How tools are registered, served, and sandboxed once you have designed them.

• OpenClaw Error Handling and Recovery Patterns →

  Backoff, circuit breakers, and dead-letter queues that belong underneath the tool layer.

• OpenClaw Human-in-the-Loop Architecture: Approval Gates and Autonomy Budgets →

  Where write tools meet approval tiers.

• OpenClaw Multi-Tenant Architecture: Isolating Agents Per Client →

  Passing a frozen tenant context into every tool call.

FAQ