> ## 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.

# Detectors — choose your packs and confirm your tools

> Settings → Detectors: turn each detector pack Off, Preview or On for a project, tell a pack what each of your tools does so its findings can be proven, and map the fields it reads.

**Settings → Detectors** controls the detector packs that check your traces for silent failures, and lets you tell each pack what your own tools do. A **pack** is a set of checks for one kind of agent: customer support, an AI product, data analysis, or marketing and analytics. The page is part of the new dashboard interface.

What a pack finds shows up as [Findings](https://docs.zespan.com/dashboard/findings.md) on traces and, once it is proven, as [Issues](https://docs.zespan.com/dashboard/issues.md).

> [!NOTE]
>
> Only **Owners** and **Admins** (the **Manage projects** permission) can read or change this page. Everyone else sees a read-only note and no controls.

## Detector packs

The **Detector packs** card lists one row per pack with what it checks, its **Mode**, and the number of checks (with how many of them are still in preview).

| Mode | What it does |
| - | - |
| **Off** | The pack does not run. |
| **Preview** | The pack runs, but its findings stay out of Issues, and only Owners and Admins see them, until you turn the pack on. Checks that are in preview stay in preview even when the pack is On. |
| **On** | The findings the pack **proves** from your stored spans show to your team and can become Issues. A check still in preview stays in preview. |

When you choose **On** for a pack that is not on yet, Zespan asks **Turn on {pack}?** first and tells you that findings the pack proves will show to your team and can become Issues. Choose **Turn on** to confirm or **Cancel** to leave the mode as it was.

> [!WARNING]
>
> **On makes proven findings Issues.** Every pack you turn on adds issues (one per check and agent) that your whole team will see. Start with **Preview**, read the findings on your traces, then turn the pack on.

If detectors are off for the whole project, the card says **Detectors are off for this project, so no pack runs.** and no pack's mode takes effect. That setting is outside this page; on a self-hosted deployment your operator sets it (see [Issues → Kinds of issue](https://docs.zespan.com/dashboard/issues.md#kinds-of-issue)).

## Confirm your tools

Some checks cannot tell what a tool does from its name alone, so Zespan suggests a **role** for each tool it has seen in your project in the last 7 days (up to 500) and lets you confirm it. The **Confirm your tools in {pack}** card is for the pack you pick in the selector at its top right. It lists only packs that have roles to confirm. A pack that reads tool names and results directly shows **Nothing to confirm**, and a project with no tool calls in the last 7 days shows **No tools yet**.

Each row shows the tool, the **Suggested role**, **What confirming changes**, and the actions.

**1. Pick the pack**

Use the pack selector. A confirmation belongs to the pack you are looking at: the same tool can have a different role in another pack, and the other pack does not use it.

**2. Read the suggestion**

Zespan suggests a role from the tool's name and description. A tool with no suggestion reads **No suggestion**. Tools with a risky role are listed first.

**3. Confirm, change, or reject**

Choose **Confirm** to accept the suggested role. Choose **Change** to pick a different role from the pack's list. Choose **Not this** to say the suggestion is wrong; the tool is then marked **Not this** and no role is used for it.

**4. Confirm risky roles one at a time**

A role that can move money, delete, send, post publicly, write to memory, approve, block or escalate is risky. Confirming it opens **Confirm {role} for this tool?** with the checks it changes. Choose **Confirm** in the dialog; each risky tool needs its own confirmation, and the dialog is shown again for the next one.

A confirmed tool shows a **Confirmed** tag.

> [!NOTE]
>
> A confirmation is **per pack** and **per tool definition**. If a confirmed tool is renamed or its parameters change, its row shows **Changed since you confirmed** and you confirm it again; until you do, the pack does not rely on it. The last role you confirmed is the one suggested again.

### What confirming changes

Each role lists the checks it affects, and a finding a check reports has a confidence of **flag** (a signal), **likely** or **proven**. Only proven findings can become Issues. Without a confirmed role, a check stays at the lower confidence. A row with no listed change shows **Nothing changes yet**.

The checks the catalogue lifts today are:

**Checks for AI products**

| Role | Risky | What confirming changes |
| - | - | - |
| Sends a message out (email, SMS, webhook) | Yes | *Private or secret data was sent out*: flag → likely. *Content from an untrusted source drove a write*: flag → likely |
| Posts publicly | Yes | *Private or secret data was sent out*: flag → likely |
| Moves money (refund, transfer, payment) | Yes | *Content from an untrusted source drove a write*: flag → likely |
| Deletes or removes something | Yes | *Content from an untrusted source drove a write*: flag → likely |
| Writes to the agent's memory | Yes | *Content from an untrusted source drove a write*: flag → likely |
| Changes a record | No | *Content from an untrusted source drove a write*: flag → likely |
| Looks up an order | No | *An amount in the answer differs from the record*: likely → proven (can become an Issue) once its fields are confirmed |
| Looks up a refund or payment | No | *An amount in the answer differs from the record*: likely → proven (can become an Issue) once its fields are confirmed |

The other roles in this pack (reads private customer data, looks up a claim, a booking or a ticket, reads content from outside, and asks for an approval or confirmation) can be confirmed, and show **Nothing changes yet**.

**Marketing and analytics checks**

| Role | What confirming changes (likely → proven, can become an Issue) |
| - | - |
| Creates a campaign | *Campaign budget differs from the request*, *Same item created more than once*, *Targeting differs from the request*, *Campaign schedule is inconsistent* |
| Updates a campaign | *Campaign budget differs from the request*, *Update changed nothing but was reported as done*, *Campaign status stated does not match the tool result*, *Campaign schedule is inconsistent* |
| Creates an audience | *Audience created with no or too few members*, *Same item created more than once* |
| Reads campaign metrics | *Reported period differs from the period queried* |

| **Customer support checks** | |
| - | - |
| Looks up an order | *A refund larger than the order was sent* (likely → proven once its fields are confirmed) |
| Issues a refund or credit | *A refund larger than the order was sent* (likely → proven once its fields are confirmed) |
| Checks the customer's identity | *An account was changed without an identity check first* (likely → proven) |
| Changes account details | Nothing on its own |
| Hands the case to a person | *A dispute or complaint was not passed on* (flag → likely) |

| **Data analysis checks** | |
| - | - |
| Runs a data query or report | *The query covers a different period than the user asked for*, *A "top N" list does not match the rows returned* (likely → proven); the freshness and ratio checks also need their field or formula confirmed |

## Fields

The **Fields** card for the selected pack shows **where in your tool calls each value the pack reads can be found**. It is used by **Checks for AI products** (order total, amount, price, floor price, cost, reported figure, subtotal, discount percent and tax rate percent), **Customer support checks** (order total and refund amount) and **Data analysis checks** (the data as-of date). A pack with nothing to map shows **No fields**.

| Column | Meaning |
| - | - |
| **Field** | The value, for example Order total, Amount, Price, Floor price, Cost or Reported figure |
| **Tool role** | The role of the tools that return it, for example Looks up an order |
| **Path** | Where it is in the tool's result, such as `total` or `order.items[].price`. Letters, digits and underscores, dots between levels, `[]` for a list, up to 8 levels. Edit it if your tool names the value differently |
| **Status** | **Suggested** (a default Zespan proposes), **Not mapped** (no path yet) or **Confirmed** |

Choose **Confirm** on a row to save its path. A field you have not confirmed keeps the check that reads it at *likely*; confirm the field and the tool role together to let the check reach *proven*.

## New checks in preview

These checks were added in November 2026. They run in **Preview** only, whatever the pack's mode, until each one passes its accuracy tests on data its builders never saw and on real transcripts. Their findings stay out of Issues until then.

| Pack | Check | What it compares | Needs your confirmation to prove | Strongest result |
| - | - | - | - | - |
| Customer support | A refund larger than the order was sent | The refund amount sent to the refund tool against the order total the lookup returned | Order and refund tools, and their fields | proven |
| Customer support | An account was changed without an identity check first | An account-change call against a successful identity check earlier in the session | Identity-check and account-change tools | proven |
| Customer support | A dispute or complaint was not passed on | A dispute or complaint in the customer's latest message against an escalation or hand-off call | The escalation tool | likely |
| Customer support | A statement you require was missing | A statement your rule requires after an action against the answer and earlier turns | A statement rule (set through the API) | proven |
| Marketing and analytics | The campaign currency differs from the request | The budget currency in the request against the currency the campaign call sets | The campaign tool | proven |
| Marketing and analytics | The frequency cap differs from the request | The frequency cap in the request against the cap the campaign call sets | The campaign tool | proven |
| Marketing and analytics | A tracking link is broken or differs from the request | Tracking parameters in landing links against well-formed parameters and the values the request gave | The campaign tool | proven |
| Marketing and analytics | The same audience was created twice under different names | Two audience creations in one trace with the same definition | No | likely |
| Data analysis | The query covers a different period than the user asked for | The period in the user's request against the query's date window | The query tool | proven |
| Data analysis | A "top N" list does not match the rows returned | A "top N" or "highest" claim against the rows the query returned | The query tool | proven |
| Data analysis | The answer calls stale data current | "Up to date" or "real-time" claims against the as-of date in the result | The query tool and its as-of field | proven |
| Data analysis | A rate in the answer does not match its inputs | A stated rate or ratio against the value recomputed from the returned figures | The query tool, its fields and a ratio formula | proven |
| AI products | A discount or tax figure does not add up | A discounted price, tax or total with tax against the value recomputed from the recorded price and rate | The order tool and its fields | proven |
| AI products | An adverse decision was given without its reason | A denial or rejection in the record against the reason given in the answer | No (your reason wording makes it more reliable) | likely |

> [!NOTE]
>
> **Strongest result** is the most a finding of that check can be. Without the confirmations in the fourth column, a finding stays at *likely* or below. Checks marked *likely* can never become Issues on their own.

## Four more packs: E-commerce, Sales and CRM, Scheduling, Coding agent

These four packs are **on by default** for every project, but every one of their checks runs in **Preview** until it passes its accuracy tests, so nothing they find reaches Issues yet. Turn a pack **Off** on this page if you do not want its previews. Like the other packs, they read the spans Zespan stored and never call a model.

| Pack | Check | What it compares | Strongest result |
| - | - | - | - |
| E-commerce | An item was ordered beyond its stock | The quantity ordered against the stock the product lookup returned | proven |
| E-commerce | A price differs from the product record | A unit price in the answer or the order against the product record | proven |
| E-commerce | A delivery date was promised that the record does not support | A delivery date in the answer against the shipping record's estimate | proven |
| E-commerce | The order total does not add up | A stated order total against the total recomputed from the order's lines, shipping, tax and discount | proven |
| Sales and CRM | A deal stage in the answer differs from what was written | The stage the answer reports against the stage the CRM write set | proven |
| Sales and CRM | A message or update went to a different contact | The contact a send or update went to against the one the user meant | proven |
| Sales and CRM | A record was created that already existed | A new contact or lead against an existing record with the same email or phone (a name alone never counts) | proven |
| Scheduling | A booked time differs from the one stated or asked for | The time the answer states or the user asked for against the booking, compared as instants across time zones | proven |
| Scheduling | Two bookings overlap | New bookings against each other and against busy time the availability lookup returned | proven |
| Coding agent | Tests were reported passing when they were not | A "tests pass" claim against the last recognised test run (pytest, vitest, jest, go test, cargo test, mocha) | proven |
| Coding agent | A file was reported changed but was not edited | Files the answer says it changed against the files the edit and write tools touched | proven |

What each pack's roles mean, for **Confirm your tools**:

| Pack | Roles |
| - | - |
| E-commerce | Looks up a product, item or stock · Looks up an order · Looks up shipping or delivery · Places or changes an order or cart |
| Sales and CRM | Looks up a deal or opportunity · Changes the stage of a deal · Looks up a contact, lead or account · Creates a contact or lead · Updates or merges a contact · Sends an email or message |
| Scheduling | Looks up availability, free time or flights · Books, schedules or changes a booking · Looks up a booking or event |
| Coding agent | Runs shell commands · Runs the test suite · Edits or writes a file · Reads a file |

> [!NOTE]
>
> Without confirmed roles and fields a finding stays at *likely* at most. Time zones whose abbreviation has several meanings (IST, CST, BST) are skipped, not guessed. Test output that was cut at the storage limit, or in a format outside the list above, gives no finding.

## API

The page uses these project routes. They need a dashboard session and the **Manage projects** permission. See the [API reference](https://docs.zespan.com/api-reference/introduction.md).

| Route | Purpose |
| - | - |
| `GET /v1/projects/{id}/functional-packs` | Packs with their mode, checks, roles and check titles |
| `PATCH /v1/projects/{id}/functional-packs/{pack}` | Set a pack's mode: `off`, `shadow` (shown as Preview) or `on` |
| `GET /v1/projects/{id}/functional-mappings/proposals?pack=` | Tools seen in the last 7 days with their suggested role and what confirming changes |
| `PATCH /v1/projects/{id}/functional-mappings/proposals` | Confirm or reject tool roles |
| `GET` and `PATCH /v1/projects/{id}/functional-mappings/fields` | Read and confirm field paths |

Mode changes, tool confirmations and field confirmations are written to the [audit log](https://docs.zespan.com/platform/audit.md).

## Next steps

* [Issues](https://docs.zespan.com/dashboard/issues.md) — where findings a pack proves show up once the pack is On
* [Findings](https://docs.zespan.com/dashboard/findings.md) — what a pack's checks report on a trace
* [Instrumentation](https://docs.zespan.com/dashboard/instrumentation.md) — which inputs your traces recorded, so checks have what they need
* [Traces](https://docs.zespan.com/dashboard/traces.md) — open the trace behind a finding


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