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

# How SignalMD works

> What you get from SignalMD, from the first calls on your board to knowing whether a fix worked, and what you can rely on in what it says.

This page follows your agent from the day you connect it to the day you know a fix worked, then sets out what you can rely on in what SignalMD tells you.

## From connection to a fix that worked

<Steps>
  <Step title="Connect an agent and approve its brief">
    You connect a Retell agent with an API key. SignalMD imports the latest 500 calls from the last 30 days, then drafts a short [brief](/concepts/the-brief) of what the agent is for and what a good call is. You correct and approve it, and approving starts the analysis.
  </Step>

  <Step title="Calls keep arriving">
    After the first import, new calls show up on their own within about 15 minutes of ending, or as soon as they end if you add SignalMD's webhook in Retell. Each call has its own page with the recording, the transcript, the steps it passed through and what each tool did. See [Calls and flow](/concepts/traces).
  </Step>

  <Step title="SignalMD reads every call">
    SignalMD works out how each call went for the caller and, when something went wrong, where and why. On a call page you see this under **Why this outcome**, **What went wrong** and **Signals**. Calls where the caller never spoke are counted in the call outcomes and are not treated as conversations.
  </Step>

  <Step title="Problems become issues">
    Problems that repeat across calls are grouped by the change that would fix them, so one issue is one repair. Each issue names a place, a cause and a change, and sits in one of five [lanes](/concepts/lanes): Hearing, Understanding, Flow and state, Speaking or Integrations. See [Issues](/concepts/issues).
  </Step>

  <Step title="Your board lists what to do first">
    **Fix** holds confirmed defects and **Improve** holds changes you control that move your numbers, each ordered by impact. A confirmed pattern whose cause SignalMD could not establish is listed apart, under **Cause not established**, and is never presented as something to fix. **Overview** shows the top of each list, and **Issues** has the full lists.
  </Step>

  <Step title="You ship a change, and SignalMD checks it">
    When you publish a new version in Retell, SignalMD shows what changed in the configuration next to what production did afterwards. It tells you when a difference is real and when there are not enough calls yet. On each issue, **By version** says whether the live version fixed it. See [Versions](/concepts/versions).
  </Step>

  <Step title="Or test the change before callers meet it">
    A call behind an issue can become a test: a simulated caller with the original caller's goal, run against a version of your agent, with personal details masked. Tests run as text conversations, so they cover Understanding, Flow and state, and Integrations. See [Test a fix](/guides/test-a-fix).
  </Step>
</Steps>

## What you can rely on

### Every issue is something you can fix

"Dead air" is something a person noticed. Nobody owns dead air. Somebody owns a lookup that takes nine seconds.

So every issue names a place (a step, a tool or a transition), a cause, and a change someone could make. A symptom that could come from several different problems is not reported as one issue.

### SignalMD says when it does not know

A wrong issue costs more than the minutes spent reading it. Once a board has been wrong a few times, people stop believing it, including when it is right.

A cause is reported only when SignalMD has confirmed it against the calls. When the calls do not show why something happened, SignalMD says **Cause not established**. The pattern stays visible, but it is never offered as a defect to fix and never gets a suggested change. That is a legitimate result, printed on purpose. See [Cause not established](/concepts/issues#cause-not-established).

A reported cause is still a hypothesis until a change proves it. That is why every issue links to the calls behind it, and why SignalMD tells you afterwards whether your fix worked.

### It works with your agent as you built it

Your steps and tools are named differently from anyone else's, and SignalMD does not depend on your names. It reads calls in other languages too, but works best on calls in English.

### Designed behaviour is not a defect

A questionnaire that comes back to the same step for each question, or a flow that asks the same questions for each vehicle, is working as built. SignalMD is designed not to report behaviour like this as a defect.

If SignalMD still flags something your agent does on purpose, answer **No** on the issue and pick **Meant to work that way**. The rejection sticks, and it is a sign that your brief should describe that behaviour.

### Callers are not defects

Someone who hears "we're closed" and hangs up without a word counts in the call outcomes, apart from the problems you can fix, because no change to your agent would stop it.

## Next steps

<CardGroup cols={2}>
  <Card title="Calls and flow" icon="route" href="/concepts/traces">
    What you see on a call page and on the Flow page.
  </Card>

  <Card title="Lanes" icon="layer-group" href="/concepts/lanes">
    The five places a defect can live, and who owns each fix.
  </Card>

  <Card title="Issues" icon="circle-exclamation" href="/concepts/issues">
    What an issue contains and how to act on it.
  </Card>

  <Card title="Versions" icon="code-compare" href="/concepts/versions">
    How to read what production did after a change.
  </Card>
</CardGroup>


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