The problem we started with

Zuper is a field service management platform with around 30 core business domains — jobs, invoices, estimates, work orders, customers, service tasks, purchase orders, timesheets, and so on. When we set out to expose Zuper to LLM agents through the Model Context Protocol (MCP), the naive shape was obvious: one MCP "tool" per REST endpoint. That gave us hundreds of surface points, and every one of them had to be right.

"Right" is a loaded word. A tool schema is right when:

• Every field it accepts is actually accepted by the API.
• Every field the API requires is either in the schema or auto-derived.
• The enums it advertises are the enums the backend enforces.
• The request-body shape is what the backend expects.
• The endpoint URL and HTTP method match reality.
• The agent gets a useful error, not a generic 400, when it's wrong.

Getting one tool right by hand is easy. Getting ~300 tools across ~30 modules right needed a different approach.

This is the story of how we built it, and what we learned along the way.

Why not just unit tests

The instinct was: unit-test each tool with mocked HTTP. We didn't take that path, for three reasons.

One, mocks lie. A unit test with a mocked API client passes when the tool's schema accepts the input and the mock returns a canned response. It says nothing about whether the real backend will accept that payload. We learned this the hard way when a "green" test suite shipped a tool that called POST on an endpoint that only responded to PUT. The backend's 404 was a real signal; the mock happily returned success.

Two, the schemas evolve daily. The MCP layer is a translation between two shapes — the agent-facing schema and the backend API contract. The backend gets updates from a different team on a different cadence. We needed tests that run against the real API, ideally on staging, so drift is caught immediately.

Three, the questions are workflow-shaped. "Can an agent create a job, attach line items, apply a per-line tax, and generate an invoice?" is not one unit test. It's a chain of six calls with state flowing between them. That's what our users care about; that's what we needed to verify.

So we built intent-based tests.

What an intent test is

An intent is a plain-English business goal, encoded as a small object:

{
  id: 'CUST-C01a',
  module: 'Customers',
  category: 'create',
  intent: 'Create a customer with name and email',
  tool: 'create_customer',
  args: () => ({
    first_name: 'Acme',
    last_name: 'Corp',
    email: 'contact@acme.example',
  }),
  onSuccess: (result, state) => { state.new_customer_id = result.customer_id; },
  verify: {
    tool: 'get_customer',
    args: state => ({ customer_id: state.new_customer_id }),
    check: r => r.customer.email === 'contact@acme.example',
  },
}

Every intent has:

• intent — a human-readable sentence that reads like a Jira ticket title.
• tool + args(state) — the tool to call and how to build its arguments from the shared session state.
• onSuccess — a hook to stash the returned identifier for downstream tests.
• verify — a follow-up read that confirms the write took effect. Not just "did the tool return 200," but "does the corresponding read tool show the field we wrote."

args is a function, not a value, because tests share state. Creating a customer produces a customer ID; later intents that create jobs or invoices for that customer consume it. The state object is threaded through the whole run.

Intents are organized by module and category (create / update / list_get) — one file per business area, one array per file.

The verify round-trip matters more than the initial call. Many silent-failure modes we later fixed — schema too loose, backend rejecting a subfield but returning 200, tax field silently dropped — only showed up in the read-back.

Where 1000+ intents came from

Writing test cases by hand doesn't scale to hundreds of tools. Writing test cases from imagination is worse — you test the happy path and miss the edge cases that actually break in production. We needed a source of test intents that reflected how real people used the product, not how engineers thought they should.

We got there by pulling from two sources:

Past support tickets and issue trackers. Every ticket the team had ever worked on described a real customer trying to do a real thing. "Customer can't mark an invoice partially-paid from the draft state" is a test intent. "Field engineer's clock-in reflected on the wrong user" is a test intent. "Percentage discount not honored when applied at line-item level" is a test intent. We walked the ticket history module by module, converted each recognizable customer flow into an intent, and folded them into the coverage suite. Every ticket that turned into an intent got a comment linking back so the next incident would find the regression test already there.

Intent libraries per customer segment. Different customers use different subsets of the platform. An HVAC service company lives in jobs, service tasks, and invoices. A property management firm lives in properties, service contracts, and recurring jobs. A distribution business lives in purchase orders, material requests, and transfer orders. Testing "does the tool work" is not the same as "does the tool work for the way this segment uses it." We built per-segment intent libraries by walking through each customer's actual workflows — using their data model (product categories, custom fields, business units) as inputs to the intents.

The two sources compounded. Ticket-derived intents caught the bugs we'd already been bitten by. Segment-derived intents caught the bugs we'd otherwise ship into a new segment blind. Together they took the suite past 1000 intents.

A side benefit we didn't expect: the intent library became documentation for the tool. Product and solutions teams can read the intent titles and immediately see what the platform can do for a specific segment. "Schedule a follow-up job for a customer with an existing service contract" is more useful than any API doc.

The rule we settled on: new bugs get intents before they get fixes. Once a customer-reported issue is in the intent suite, it stays covered forever. Fix without an intent, and it comes back.

The runner: field-strip retry

Real APIs fail for surprising reasons. A schema evolves, an enum tightens, a required field starts erroring out. When that happens in a test suite, we don't want to abandon the whole intent; we want to isolate which field is the culprit.

So the runner has a field-strip retry loop. On tool error, it:

1. Pattern-matches the error message for a suspect field name.
2. Removes that field from the arguments.
3. Retries the call.
4. Loops until success, or until every optional field has been stripped.

At the end of the run it reports two verdicts per field: VERIFIED (the field was accepted and reflected in the verify read) or UNVERIFIED (the field was stripped during retry).

The point isn't to make failing tests pass. It's to produce a coverage map. When we saw one field marked UNVERIFIED across forty different tests, we knew the whole schema for that field had drifted from the backend — one bug, not forty.

The coverage document — one per module

Each module owns two generated files:

• A run report — the summary. Every intent, PASS/FAIL/VERIFY_FAILED, which fields were stripped, which are UNVERIFIED.
• A failure guide — each failure gets a stanza with the tool name, error message, stripped fields, likely cause, and a "suggested fix" line.

These aren't just artifacts — they became the primary planning surface. Every session started by reading the last run's failure guide. Fix, re-run, watch FAIL count drop, watch PASS count climb.

The pattern we settled into:

Round 1: baseline run — enumerate every failure.
Round 2: fix the top N failures, re-run just those tests.
Round 3: re-run the whole module. New failures? Different failures?
Round 4: expand coverage — add intents for edge cases surfaced during fixes.

A concrete example: the tax and line-item audit. Round 1 showed several "create estimate with ad-hoc tax" intents as VERIFY_FAILED. Investigation revealed the backend requires a tax UID reference for every document-level tax entry — it hard-rejects ad-hoc {name, percent} forms. We narrowed the schema to require the UID. Re-ran. Passed. Added Round-2 intents for line-item-level tax and markup. Passed. Added Round-3 intents for the update path, tax-exempt overrides, mixed inheritance. Passed. Coverage went from 4 tax intents to 22 in one week, all green.

The coverage doc is a ratchet: it only counts intents that VERIFY, and the verified count only goes up.

Adversarial verification with parallel agents

Half the bugs we caught weren't in the runner output. They were in the schema itself — fields that looked plausible but weren't in the backend, enums that shipped extra values the backend would reject.

For those, the runner alone can't help — a schema that never gets exercised by an intent test can be arbitrarily wrong and nobody notices. So we ran periodic audit passes.

The pattern:

1. Spawn 4–6 parallel research agents. Each takes a subset of modules.
2. Each agent reads the MCP tool file, the corresponding webapp form component, and the backend controller. It reports a table: field-by-field, what's in the tool vs the UI vs the backend.
3. Agent findings are claims, not truth. Every high-severity claim gets spot-verified against the actual source before it hits the audit doc.
4. Consolidate into a single module-wise gap doc.

The reject-before-trust step is important. Agents are helpful and confidently wrong in equal measure. In one audit round, an agent claimed a listing tool used the wrong enum values. We opened the file — the actual enum was correct; the agent had misread a docstring elsewhere in the same file. We rejected that claim in the write-up. In the same round, another agent flagged a deposit-recording tool as calling POST when the backend registered PUT. We opened the file — real bug, six months old, silent behind an outer try/catch.

Every claim gets grep-verified before it becomes a finding. This one habit cut the false-positive rate on our audit docs from ~30% to under 5%.

When docs aren't enough: browser automation as a discovery tool

Roughly a third of the way through the project, we hit a wall: the internal API reference documents were incomplete. Some endpoints were undocumented. Others were documented but omitted fields the UI was actually sending. Some documented fields were flagged "optional" but were required in specific configurations. Without ground truth for those endpoints, we were guessing.

So we brought browser automation into the loop.

The pattern was simple: script the webapp's real workflow end-to-end — log in, create a job, add products, set a tax, save, refresh — and capture every network request. Each captured request gave us a real payload: exact field names, exact nesting, exact enum values, exact wrappers. When our schema disagreed with the payload, the schema was wrong.

A few things it exposed that we'd have missed otherwise:

• Undocumented approval hooks. A specific status transition sent an extra approval identifier the API reference didn't mention. The browser automation caught it on the first pass.
• Field-nesting quirks. The webapp nests certain settings (billing frequency, payment term) under a nested accounts object on save. Our tool was sending them flat. The API "accepted" both shapes but silently discarded the flat one. The captured payload made the correct shape visible.
• Company-config-gated behaviors. Some fields only appear in the payload when a company setting is on. Running the automation against two configurations side by side let us design a schema that handled either.

Browser automation wasn't a replacement for the API docs or the backend source. It was the fastest way to answer "what does the UI actually send?" when the other two disagreed, and to catch the hidden third case both had missed. The reusable rule: when in doubt, capture the network traffic.

The module dependency matrix

Ordering modules by "business criticality" was the first cut. But criticality isn't the same as "safe to fix first." A tool schema for jobs depends on customers existing, products existing, tax IDs existing, business units existing. Fix jobs first and half your tests fail because the entities they depend on aren't seeded.

So we built a module dependency matrix — a per-module document mapping every upstream dependency:

Customer domain
  ├─ Depends on: categories, organizations, tax groups, pricelists
  └─ Depended on by: jobs, invoices, estimates, projects, contracts, ...

Job domain
  ├─ Depends on: customer, product, product category, job category,
  │              user, team, business unit, service tasks, tax
  └─ Depended on by: invoice, estimate, service report, timelog, ...

Roughly two dozen of these documents now live alongside the code, one per business domain. Each names its foreign-key relationships, the exact fields that carry the reference, and any known quirks (e.g. "the job's property inherits from the customer if omitted, but only when the customer has a default property set").

Two immediate benefits:

Testing order becomes deterministic. The seed script that populates the shared session state reads the dependency graph and creates entities in topological order. Customers before jobs, products before line items, tax before invoices. No more "test failed because the customer ID is empty."

Field audits become sharper. When we're auditing an invoice-creation tool, the customer dependency doc tells us which fields flow into the customer lookup, which fields the invoice inherits automatically, and which ones a manual override is expected. That's usually what the API docs leave implicit.

We also generated companion API reference documents — one per module — that consolidate every endpoint we call, its verified request shape (from network capture + backend source cross-check), and its response shape. These sit alongside the dependency matrix. The pair of documents — dependency map + verified API reference — became the input to every new intent-suite expansion and every audit round. If a claim in a coverage doc contradicts one of these two, the coverage doc gets updated first.

Module-by-module progression

We didn't try to fix all tools at once. We ordered modules by:

1. Business criticality (jobs first, then invoices and estimates, then service tasks, then material requests, then everything else).
2. Intent-suite coverage (biggest suites first — they surface the most bugs per hour).
3. Cross-module dependency (fix customers before jobs, because job creation needs customer state).

Per module, the loop was:

1. Baseline — run current intents, capture the coverage report.
2. Field audit — parallel research pass to find missing or wrong fields vs the UI and the backend.
3. Fix critical — schema and endpoint corrections.
4. Expand coverage — new intents for the fields just added.
5. Regression — re-run the whole module; add any newly surfaced failures to the queue.

For the jobs module alone, that loop produced dozens of field-level fixes and roughly doubled the passing intent count.

What surprised us

Silent overrides. Several endpoints happily accept fields they then ignore. The backend's tax calculator overwrites caller-supplied tax name and percent from the tax-master lookup, regardless of what the caller sent. Our MCP was faithfully passing through fields the backend would silently drop, giving agents the illusion of setting them. Fixing this meant narrowing schemas below what the backend would accept — trading permissiveness for predictability.

The unit-price / price schism. Jobs use one field name for line-item price. Invoices and estimates use a different one. A converter tool translates one to the other. No documentation of the flip anywhere. An agent using our tools cross-module has to know this by feel unless the tool descriptions call it out. We added the notes.

Status enums that lie. One status-update tool accepted status values as write targets that the backend never allows to be set directly — some are computed automatically from other actions, some are display-only. An agent that tried those transitions through MCP would get a generic 4xx and no clear signal. Narrowing the write enum was a one-line fix; finding the mismatch was hours of matrix-reading.

The auto-derive trap. Some create tools mark fields optional even though the backend requires them — because when the caller passes a parent entity, the tool auto-copies the required fields from that parent. The schema looks broken until you read the execute body. Documentation matters more than schema strictness once the tool starts doing derivation work.

The tooling that kept us moving

• A restart-between-chunks runner — the upstream MCP session state degrades under sustained load; a chunked runner is a workaround, not a fix, but it kept the suite moving.
• A shared session-state file — pre-seeded IDs for common entities (customer, product, tax, category), populated once via a seed script; every test run starts from it.
• An ID-prefix filter — a CLI flag to re-run just one group of intents by ID prefix. Made the "fix, run three tests, re-run all" loop fast enough to stay in flow.
• An env-file credential loader — no hardcoding, no accidental leaking of production keys into a staging suite.

None of these are impressive individually. Together, they made large-scale coverage tractable.

What we'd change next time

Start with the coverage doc, not the tool. The first tools we built had shallow schemas because we hadn't scoped the UI form's field list yet. We ended up rebuilding several tools twice. Working from a coverage matrix — every field in the UI form, every field in the backend schema, every field we plan to expose — would have front-loaded the design work.

Adopt a strict "tighten before ship" rule. Schemas are easy to loosen after the fact and painful to tighten. Every "make it optional for now" we deferred came back as a support ticket. Better to start narrow and open up on demand.

Contract tests, not just integration tests. The intent suite exercises real endpoints, but it doesn't lock the backend response shape. A field rename on the backend silently breaks our verify checks. A layer of contract tests that snapshot response schemas would have caught two silent regressions we found only by luck.

Backend-side gate for enums. Many enum bugs (statuses in write enums that shouldn't be, transition targets the backend won't accept) exist because the backend accepts one set of values as input and produces a different set as output. The backend should either publish the write-side matrix or the MCP should mirror the matrix explicitly.

Where the project stands

• Approaching 300 tools across roughly 30 modules
• 1000+ intent tests, sourced from past tickets and per-segment customer workflow libraries
• Intent suites for the top business modules: jobs, invoices, estimates, customers, service tasks, material requests, timesheets, purchase orders
• Live-API test runs on staging on demand
• Per-module coverage docs updated on every run
• Field-gap audits checked in with prioritized fix queues

The core lesson is unglamorous but real: at scale, the test suite is the design tool. Intents make the requirements concrete. Coverage docs make the gaps visible. Round-by-round iteration makes the delta shippable. We didn't write hundreds of tools right on the first try. We wrote them approximately, and then let the tests tell us where they were wrong.

That, more than anything, is how the Zuper MCP got built.