> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zespan.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tool drift — when a tool, key or quota changes under your agents

> Zespan watches the tools your agents call for a changed answer shape, a missing MCP tool, refused or throttled calls, a key that is about to expire and a quota that is about to run out, from spans you already send, with no model call.

Agents break with no deploy of yours when something they call changes underneath them: a tool's API answers in a new shape, an MCP server drops a tool, a key expires, a quota runs out. I notice these from the spans you already send and say so on [Home](https://docs.zespan.com/dashboard/home.md). I never call a model and never read a secret.

The page is at **Tool drift**. It has no sidebar item: open it from the **Tool drift** button on [Tools](https://docs.zespan.com/dashboard/tools.md), from a drift row on Home, or from an [HTTP target](https://docs.zespan.com/dashboard/http-targets.md) that shows a key date.

## What it watches

| Signal | What I look for | Where it shows |
| - | - | - |
| A tool answers in a new shape | A result shape I had not seen for that tool, and its errors or the agent's failures moved | **Critical** when it breaks, otherwise a **Needs you** question |
| An agent calls a tool in a new way | A new argument shape | A row in the Logbook (it is usually your own change) |
| A tool's declared schema changed | A new schema in the tool definitions | A row in the Logbook |
| An MCP tool is gone | A tool an agent used is no longer offered and calls to it now fail | **Critical** when calls fail, otherwise a **Needs you** question |
| Calls refused as unauthorized | Several calls in an hour refused with a 401 or 403 style answer | **Critical**, with **Renew the key** |
| Calls throttled | At least a fifth of a tool's calls in an hour were rate limited, from 10 calls up | **Critical** |
| Out of credits | Calls refused because the account is out of credits or over its billing quota | **Critical**, with **Open the provider settings** |
| A key with an expiry date | A date you gave me, or one read from the key itself (see below) | **Coming up** within 30 days, **Needs you** within 7 |
| A quota near its limit | A quota you gave me, with the calls I counted | **Coming up** with a projected date, **Needs you** at 90 percent |

## What "breaking" means

I call a new answer shape or a missing MCP tool **breaking** only when I measured it. In the 2 hours after I first saw it, compared with the same tool's previous 7 days, one of these holds:

* the tool's error share rose by at least 10 percentage points, with at least 5 errors; or
* the agent's failed-run share rose by at least 5 percentage points, with at least 20 runs, and the new shape is in at least half of those failed runs.

With fewer runs than that, I say "Not enough runs yet to tell if it breaks anything" and ask you whether the change was expected. A change that comes soon after you changed redaction or capture settings is labelled as such and is never called breaking. A breaking change on a tool whose role moves money or deletes data ranks higher on Home, like a failed issue on such a tool.

If no calls to the tool arrive after a change, I do not call it fixed: "No calls to `lookup_order` since 14:12, so I can't tell if it's back to normal."

## Shapes only

I keep the keys and types of a tool's input and output, never a value and never a hash of a value. The change view shows only keys and types:

```text theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
~ amount: number to string
+ total: number
- note: string
```

`+` is a key that is new, `-` one that is gone, `~` one whose type changed.

A tool whose input and output are not captured is listed as **not checked**, never as unchanged. A project that sends many different tool names in a day can reach a daily limit on recorded shapes; the tools past it are listed as not checked too.

## What the page shows

* **My last check.** When I last checked, and how many tools. A check that ran out of time says so, and if my checks have stopped the page says "My checks are not running right now" instead of showing the stamp as current. With no check on record, the page does not say your tools are unchanged. In shadow mode a label says I am recording but Home shows nothing yet.
* **Open changes.** Each change with its kind, subject, agent, when it was first and last seen, the measured counts in words, and the before and after shapes. Owners, admins and editors get **It was expected**, which closes the change and keeps it from coming back for that same change. It affects only this project.
* **Tools I did not check.** Each tool with the reason: `no_capture` or `over_cap`. If I could not read the list, the page says so instead of showing an empty list.
* **Key dates** and **Quotas**: the watches you gave me, with a form to add one.

## Add a key expiry date

**1. Open Tool drift**

From **Tools**, a drift row on Home, or an HTTP target.

**2. Fill in Key dates**

Give the key a name, say what uses it (a tool, a model provider, an HTTP target or a model connection) and its name, and pick the day it expires. The day ends at 23:59 UTC, a day that has already passed is refused, and the date is shown everywhere as the day you typed. The form has no field for the key itself, and I never ask for it.

**3. Save key date**

Within 30 days the key shows under **Coming up** on Home with the date and where it came from. Within 7 days it becomes a **Needs you** card. If the date passes and I see no refused calls, I ask whether the date is still right.

> [!NOTE]
>
> When you save an HTTP target with a bearer token that is a JWT, I read the token's own expiry date once, from what you sent, and keep only the date. I never decrypt a stored key later. The target then shows "Key expires on {date} (from the key itself)". A token that is not a JWT gets no date, and an older target has none until you save it again.

## Add a quota

**1. Fill in Quotas**

Give the quota a name, name at least one provider, tool or model to count, your limit in calls, the period (day or month) and when it resets: a time of day in UTC for a day quota, a day from 1 to 28 for a month quota.

**2. Save quota**

The limit is your number. I count the matching calls myself, so **Used** is measured. With at least 3 days of data in the period, I project when it runs out at this week's pace; before that the page says "not enough days yet" and there is no date. If I could not read the count, it says "not read".

Only owners, admins and editors can add or remove key dates and quotas; everyone else sees them read-only. **Remove** asks first, because removing a watch closes its change and writes a Logbook row. You can add them even while tool drift is off, but nothing reads them until it is on.

## Where it shows on Home

* **Critical now**: a breaking change, a refused-call or throttling run, or an out-of-credits run, in my words ("I see this now: ...") with one action.
* **Coming up**: a key expiry or a quota with a date and its basis ("Date from you", "Date from the key itself"). A date without a basis is never shown.
* **Needs you**: renew a key, say whether a new shape was expected, raise or reset a quota.
* **Logbook**: new argument shapes, new declared schemas, changes that went back to normal. On a day with nothing found, one roll-up: "I checked your tools 12 times on Nov 21 (UTC); no tool changed." The count is for the UTC day, and I say nothing if I could not count today's events.
* **How I checked**: "I checked the shapes of 12 tools and their errors at 14:12", the tools I could not check and why, a check that ran out of time, or "I could not read my tool checks just now."

## Next steps

* [Tools](https://docs.zespan.com/dashboard/tools.md): the tools your agents call, with how often they fail
* [Home](https://docs.zespan.com/dashboard/home.md): where drift shows up
* [HTTP targets](https://docs.zespan.com/dashboard/http-targets.md): the key date read from a bearer token
* [Model lifecycle](https://docs.zespan.com/dashboard/model-lifecycle.md): the same kind of warning for retiring models
* [Canary](https://docs.zespan.com/dashboard/canary.md): scheduled test runs of an agent


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.