DEV Community: Frihet

Designing MCP tools an agent won't misuse

berthelius — Sun, 09 Aug 2026 08:00:11 +0000

The first article in this series made a pair of claims. One: an AI-native product is an MCP server that lets an agent do things, not a chat widget that talks about them. Two: every write an agent can invoke needs idempotency and typed, recoverable errors, because agents retry and fan out by default.

Both took typed schemas for granted. Of course you validate your inputs — zod on the way in, reject the malformed call. That's table stakes. This article is about the failure mode that survives input validation: misuse.

An agent almost never sends you malformed JSON. It sends you well-formed wrong. The payload passes every schema check and still does the wrong thing, because a language model is a probabilistic caller reasoning from your tool descriptions, not a developer who read your docs. Typing the inputs stops garbage. It does nothing about a valid call that shouldn't have been made. Designing against that is a different job.

Four ways a well-typed call still goes wrong

Watch a model drive a real tool catalog and the same four failures recur:

Wrong tool. You expose update_invoice and send_invoice. The agent means "send" but the descriptions overlap, so it calls "update" with a status field and assumes that mailed the PDF. Every argument is valid. Nothing was sent.
Valid-but-wrong argument. A field takes a free-text region string. The model writes "Canary Islands", "canarias", "ES-CN", or "islas canarias" on different runs. All are strings. Your tax engine understands exactly one of them.
Wrong order / missing precondition. The agent issues a credit note against an invoice that was never finalized, or bills a client it hasn't created. The call is shaped correctly; the world isn't in the state the call assumes.
Can't recover. Something fails and the error is a stringified 500. The model can't tell "back off and retry" from "this will never work," so it either gives up or hammers the endpoint.

None of these is an input-validation bug. All four are interface design bugs. The good news: the same MCP surface that lets an agent operate your domain also gives you the levers to prevent them.

Lever 1 — constrain the input space, don't just type it

region: z.string() is typed. It is also an open door: infinitely many valid strings, one of which your server accepts. The fix is old and boring — make illegal states unrepresentable — and it maps directly onto tool schemas. Replace the open type with a closed one, so the model chooses from a menu instead of inventing a value.

Here's the real shape from the Frihet MCP server's invoice tools. The fiscal zone that decides whether a line carries mainland IVA, Canary Islands IGIC, or an exemption is not a string — it's an enum, and the operation type is a two-value enum:

// src/tools/invoices.ts — invoiceFiscalFields: fiscal zone drives IVA vs IGIC vs exempt, never a free string
clientLocation: z
  .enum(["peninsula", "canarias", "ceuta_melilla", "eu", "world"])
  .optional()
  .describe("Fiscal zone driving IVA vs IGIC vs exempt / Zona fiscal"),

operationType: z
  .enum(["service", "goods"])
  .optional()
  .describe("Operation type (service or goods) / Tipo de operacion"),

irpfRate: z
  .number()
  .min(0)
  .max(100)
  .optional()
  .describe("IRPF withholding % (retencion autonomo ES) / Retencion IRPF %"),

Three constraints, three classes of misuse closed off. The enum collapses "Canary Islands" and its four spellings into one legal token the model can't get wrong — and the enum values are visible to the model at tool-discovery time, so it picks rather than guesses. The .min(0).max(100) on a percentage means the agent can't submit a 150% withholding because it misread a prompt. And a two-value operationType enum is a decision the model makes explicitly instead of leaving your server to infer intent.

The rule of thumb: for every input field, ask "how many values would I accept here, and how many does the domain actually allow?" When those numbers differ, the gap is where an agent will eventually land. Close it with an enum, a numeric bound, a length cap, or a discriminated union — in the schema, where the model can see it, not in a 422 it discovers after the fact.

Lever 2 — the description and the annotations are part of the contract

A tool's description is not a comment. It's the only thing the model reads to decide which tool to call. Overlapping, vague descriptions are how you get the wrong-tool failure. Two tools whose descriptions could each plausibly answer "send this invoice" is a routing bug you shipped, and no amount of input typing fixes it. Descriptions should be disjoint and imperative: name the one job each tool does and, where useful, name what it does not do.

MCP gives you a second, machine-readable channel for this: tool annotations. They're advisory hints attached to each registration — not enforcement, but signals the host can act on. The Frihet server tags every tool with one of four constants:

// src/tools/shared.ts — safety annotations, applied per tool
export const READ_ONLY_ANNOTATIONS = { readOnlyHint: true,  destructiveHint: false, idempotentHint: true,  openWorldHint: false };
export const CREATE_ANNOTATIONS    = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false };
export const UPDATE_ANNOTATIONS    = { readOnlyHint: false, destructiveHint: false, idempotentHint: true,  openWorldHint: false };
export const DELETE_ANNOTATIONS    = { readOnlyHint: false, destructiveHint: true,  idempotentHint: true,  openWorldHint: false };

Read what those flags encode. A read tool is safe and idempotent — a host can auto-approve it. A create tool is idempotentHint: false: calling it twice is not safe, which is precisely the signal that says "this write needs an idempotency key". A delete tool is destructiveHint: true — the flag a well-behaved client uses to require human confirmation before letting an agent run it unattended.

These are hints, and the spec is explicit that a client shouldn't make security decisions on annotations alone — real enforcement still lives server-side in auth and validation. But as a design tool they're doing something important: they let the host gate the agent's autonomy per tool instead of all-or-nothing. Auto-run the reads, checkpoint the deletes. Misuse-by-blast-radius, contained by metadata you declared once.

Lever 3 — type the output and the errors, so recovery is deterministic

The last two failure modes — wrong order and can't-recover — are both about what the model learns after the call.

Typed output is what lets an agent chain calls without hallucinating the shape of your data. On the Frihet server every tool returns structured output via an outputSchema, and list tools return real pagination — { data, total, limit, offset } — so an agent pages deterministically instead of guessing whether it saw everything. Prose replies force the model to parse, and parsing is where it invents fields that were never there.

Errors are the other half, and they're where "can't recover" is won or lost. A stack trace tells a model nothing. A stable, typed error tells it what went wrong and what to do next. The server maps every failure onto one error class with a machine-readable code:

// src/client.ts
export class FrihetApiError extends Error {
  constructor(
    public readonly statusCode: number,
    public readonly errorCode: string,   // stable string, e.g. "rate_limit_exceeded"
    message?: string,
  ) { super(message ?? errorCode); }
}

The agent branches on errorCode, never on a stringified status. A rate_limit_exceeded means back off — and the server already retries 429s with exponential backoff before it ever surfaces one, honoring the Retry-After header. A request_timeout means the write may or may not have landed, so retry with the same idempotency key. A validation code means the payload is wrong; retrying it unchanged just burns the 100-requests-per-minute budget against a wall. (The retry taxonomy itself — retryable vs terminal, backoff with jitter — is a subject of its own; the point here is that the code is the interface that makes those decisions possible.)

Same idea for the wrong-order failure: return a precise, named error the agent can act on — "finalize the invoice before issuing a credit note" — instead of a generic 400. A typed error is an instruction. A 500 is a dead end.

The design review that catches misuse

Before you register a tool, run it past four questions. They map one-to-one onto the failure modes:

Wrong tool? Is this tool's description disjoint from every other tool's, and does it name the one job it does? Could a model reasonably confuse it with a neighbor?
Valid-but-wrong argument? For every field, does the schema allow only what the domain allows — enums over free strings, bounded numbers, discriminated unions — with the legal values visible at discovery time?
Autonomy gating? Are read / create / update / delete annotated so a host can auto-approve the safe ones and checkpoint the destructive ones? Does the create tool that isn't idempotent say so?
Recoverable? Does every failure return a stable errorCode and structured output the agent can branch on and page through — never a stringified 500?

Typed inputs keep malformed calls out. Designing the surface — constrained schemas, disjoint descriptions, safety annotations, typed errors — keeps wrong calls out. The first is validation. The second is the actual interface an agent operates, and it's the one that decides whether 157 tools are 157 capabilities or 157 ways to get it subtly wrong.

Earlier in this series: why AI-native means an MCP server, not a chatbot.

Make agent-callable writes idempotent, or lose data

berthelius — Sun, 02 Aug 2026 08:00:11 +0000

An agent-native product isn't a chatbot bolted onto a CRUD app — it's an MCP server that lets an agent do things. Read invoices, create expenses, mark a client overdue. The demo is easy. The part that decides whether the thing survives contact with real traffic is the layer nobody screenshots: what happens when a write is sent twice.

This is the unglamorous half of agent-native engineering. Every write operation an agent can invoke needs idempotency, safe retries, and typed recoverable errors — not as a nice-to-have, but as the difference between a product and a liability. Here's why, and how to build it.

Agents turn "at-least-once" from a footnote into a daily event

Distributed systems people have known forever that networks give you at-least-once delivery, not exactly-once. A request goes out, the response gets lost on the way back, the caller doesn't know if the write landed, so it retries. With a human clicking a button, this is rare enough to hand-wave.

Agents remove the hand-wave. Three things about how agents call tools push duplicate writes from "edge case" to "Tuesday":

They retry automatically. A well-behaved MCP client backs off and retries on 429 and 5xx. The Frihet MCP server (github.com/Frihet-io/frihet-mcp) enforces 100 requests per minute per fri_ key, and its own client retries with exponential backoff when it hits that ceiling. A retry after a 429 is supposed to happen — which means every write behind that endpoint has to survive being delivered more than once.
They time out and resume. An agent loop hits a wall-clock limit mid-tool-call, the session gets resumed, and the planner — having never seen a result — reasonably decides to "create the invoice" again.
They fan out. Give a model a goal ("bill everyone for last month") and it will happily issue parallel tool calls. Two of them racing on the same logical write is now a concurrency problem, not a theoretical one.

MCP itself does not save you here. A tool call is just RPC over JSON — the protocol says nothing about whether invoking create_invoice twice creates one invoice or two. That contract is entirely yours to define on the server. If you don't define it, you've defined it as "two."

For a read tool, a duplicate is free. For a write tool in a fiscal domain — an ERP that prepares VeriFactu records, IVA and IRPF filings — a duplicate is a phantom invoice in someone's tax quarter. The blast radius is exactly why the boring layer matters.

Idempotency keys: the client names the request, once

The fix is to let the caller assign a stable identity to a logical operation, independent of how many times it's physically delivered. That's an idempotency key: a client-generated token (usually a UUID) that stays the same across retries of the same intended write, and changes for a genuinely new one.

The rule for the client is simple: generate the key once, at the point of intent, and reuse it for every retry of that same intent. If the agent decides to bill a client, it mints one key and carries it through all four delivery attempts. When it decides to bill a different client, it mints a new one.

The server's job is to make the key mean something: the first time it sees a key, do the work and remember the result; every subsequent time, return the remembered result without touching the database again.

The subtlety that trips people up is atomicity. "Check if the key exists, then insert it" is a race — two concurrent retries both read "not found" and both do the work. The claim has to be a single atomic operation, which in Postgres is an INSERT ... ON CONFLICT DO NOTHING and in most KV stores a compare-and-set.

import { createHash } from "node:crypto";

interface WriteContext {
  accountId: string;      // scope keys per tenant — never globally
  toolName: string;       // e.g. "create_invoice"
  idempotencyKey: string; // client-supplied, stable across retries
}

async function runOnce<T>(
  ctx: WriteContext,
  payload: unknown,
  work: () => Promise<T>,
): Promise<T> {
  const slot = `${ctx.accountId}:${ctx.toolName}:${ctx.idempotencyKey}`;
  const fingerprint = createHash("sha256")
    .update(JSON.stringify(payload))
    .digest("hex");

  // Atomic claim: only the FIRST caller inserts the row.
  const claim = await store.claim(slot, fingerprint); // INSERT ... ON CONFLICT DO NOTHING
  if (!claim.inserted) {
    // Key already seen. Same body  -> return the stored result.
    // Different body -> the client reused a key for a new request. Reject.
    if (claim.fingerprint !== fingerprint) {
      throw new ToolError("idempotency_key_reused", {
        retryable: false,
        message: "Idempotency key was reused with a different payload.",
      });
    }
    return store.awaitResult<T>(slot); // return the SAME result, never re-run
  }

  try {
    const result = await work();
    await store.complete(slot, result);
    return result;
  } catch (err) {
    await store.fail(slot); // release the slot so a genuine retry can proceed
    throw err;
  }
}

Three things this snippet gets right that naive versions miss:

The key is scoped per tenant. Two accounts can generate the same UUID; without accountId in the slot, one customer's retry could return another's invoice. Scope aggressively.
The payload is fingerprinted. Reusing a key with a different body is almost always a client bug. Returning the old result silently would hide it; creating a new record would defeat the point. Rejecting it with a typed error is the honest answer.
The stored result is returned verbatim. The whole contract is that the second caller gets exactly what the first caller got — same invoice id, same numbers — not a fresh write that happens to look similar.

How long do you keep the record? Long enough to outlive any retry storm — hours to a day is typical, and it's a deliberate trade-off, not a default. Too short and a slow retry slips through the window and double-writes; too long and you're storing every request body forever.

Safe retries need a taxonomy, not a `try/catch`

Idempotency makes retrying safe. It doesn't tell you when to retry. That decision depends entirely on what went wrong, and "an error happened" is not enough information to make it.

A 429 or 503 is transient — back off and retry.
A 422 validation_failed is permanent — retrying the same bad payload a thousand times just burns your rate limit against a wall.
A 504 gateway timeout is the genuinely hard one: the write may or may not have landed. This is the exact case idempotency was built for. You retry with the same key, and the server either finishes the original work or hands back the result it already produced. Without the key, a retry here is how you double-bill someone.

For the agent to make this call, the error has to be machine-readable. A stringified 500 Internal Server Error forces the model to guess from prose, and models guess wrong. Ship a typed error taxonomy instead: a stable code, an explicit retryable boolean, and a hint for how long to wait.

type ErrorCode =
  | "rate_limited"          // 429 — back off, then retry
  | "upstream_timeout"      // 504 — retry with the SAME idempotency key
  | "validation_failed"     // 422 — do NOT retry; the payload is wrong
  | "insufficient_funds"    // 402 — do NOT retry; surface to the user
  | "idempotency_key_reused"//     — client bug; do NOT retry
  | "conflict";             // 409 — a concurrent write won; re-read, then decide

class ToolError extends Error {
  constructor(
    public readonly code: ErrorCode,
    public readonly meta: {
      retryable: boolean;
      message: string;
      retryAfterMs?: number;
    },
  ) {
    super(meta.message);
  }
}

// The client/agent reads `retryable` — it never parses a stringified 500.
function isRetryable(err: unknown): err is ToolError {
  return err instanceof ToolError && err.meta.retryable;
}

Pair the taxonomy with exponential backoff and jitter. Backoff without jitter means every one of your fanned-out tool calls that got rate-limited retries at the same instant — a synchronized stampede that trips the limit again. Randomizing the delay spreads the herd out. And cap the attempts: retryable does not mean retry forever.

Note that retryable lives on the server's side of the contract but is consumed by the client. That's the point — the server knows whether a write is safe to repeat, so it says so explicitly instead of making every caller reverse-engineer the answer from an HTTP status and a hope.

Why this is the whole game for agent-native products

A demo proves an agent can create an invoice. Production asks a harder question: when the same instruction gets delivered twice — because a network blipped, a session resumed, or a 429 triggered the retry the client was designed to perform — does your customer end up with one invoice or two?

Consider the surface area. A server like Frihet exposes 157 tools over mcp.frihet.io, a large share of them writes into an ERP that generates real tax records. Every one of those write tools is a place where at-least-once delivery meets a fiscal side effect. Idempotency keys, atomic server-side dedup, and typed recoverable errors are what turn that surface from a duplicate-data generator into something an agent can hammer safely at 100 requests a minute. That contract is the argument of this article: it is what every server on the other end of an agent owes its callers. It is also the least glamorous work in the codebase and the work that determines whether the product is trustworthy.

The industry spent a decade learning this for payments — it's why Stripe made idempotency keys a first-class header. Agents make the lesson urgent everywhere at once, because agents retry, resume, and fan out by default. If you're building anything an agent can write to, treat this as the foundation, not the polish. The chatbot is the part users see. This is the part that keeps their data correct.

Next up: designing tool schemas an agent won't misuse — types, enums, and error contracts as the real interface.

Zero Admin: The Complete Stack to Run Your Business on Autopilot

berthelius — Sun, 05 Apr 2026 10:00:00 +0000

Picture this: a client accepts your quote on a Tuesday at 11:00 AM. At 11:01, the invoice is in their inbox. Thursday, they pay. The payment reconciles against the invoice automatically. At the end of the quarter, your sales tax is calculated, your tax forms are pre-filled, and you have not opened a spreadsheet in three months.

This is not a fantasy. It is a stack you can build today, in under an hour.

This guide is a complete blueprint. Not "which tool to use" but the entire flow: from the first client handshake to your quarterly tax filing. Step by step, no filler.

What Zero Admin actually means (and what it does not)

Zero Admin is not zero effort. It is zero unnecessary effort.

The distinction matters. Every business has two kinds of administrative work:

Mechanical work: copying data between platforms, categorizing expenses by hand, matching bank transactions to invoices, calculating quarterly tax, filling out tax forms. This work does not require human intelligence. It requires time. And it steals 10+ hours from your week.

Intellectual work: approving an unusual expense, deciding whether a project is profitable, negotiating payment terms with a client, choosing between investing and saving. This work actually needs you.

:::quote
Zero Admin = the system handles data, calculations, filing, and repetition. You handle relationships, strategy, and decisions.
:::

The goal is not to eliminate management. It is to eliminate the management that adds nothing. Let the back office run as a silent system in the background while you do the work that matters.

The complete flow, step by step

This is what happens when the right pieces talk to each other. An end-to-end flow, from the moment a client says "yes" to the moment the tax authority has its numbers.

Step 1: Client accepts → Invoice sent

The client accepts your quote. Frihet converts that quote into an invoice with one click. Same data, same line items, same client. Nothing re-typed.

The invoice is sent automatically via email with a payment link (if you have Stripe Connect active). The client receives a professional PDF and can pay directly from the email.