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

# Tools

> All 15 MCP tools, scopes, rate buckets, and behaviour worth knowing.

Each tool maps to a Partner API operation and returns its JSON as text. Lists return the compact view unless `view: "full"` is passed; `get_*` tools return the full view. Field meanings are in the [API reference](/api/overview).

## Inventory

| Tool              | Does                                                                                                             | API equivalent               | Scope                           | Rate bucket | Annotations     |
| ----------------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------- | ------------------------------- | ----------- | --------------- |
| `whoami`          | Organisation, key name, scopes and limits                                                                        |                              | any valid key                   |             | read-only       |
| `list_companies`  | Tracked companies with their latest signal; filter by `status`, `stage`, `classification`                        | `GET /tracker`               | `tracker:read`                  | read        | read-only       |
| `get_company`     | One company with enrichment progress (`operation`); use to poll                                                  | `GET /tracker/{id}`          | `tracker:read`                  | read        | read-only       |
| `add_company`     | Start tracking a company and founders                                                                            | `POST /tracker`              | `tracker:write`                 | create      | idempotent      |
| `update_company`  | Change rules, recipients, cadence, tags, founders, or pause/resume (`status`)                                    | `PATCH /tracker/{id}`        | `tracker:write`                 | write       | idempotent      |
| `refresh_company` | Run the tracker now                                                                                              | `POST /tracker/{id}/refresh` | `tracker:write`                 | refresh     |                 |
| `remove_company`  | Permanently stop tracking and delete history                                                                     | `DELETE /tracker/{id}`       | `tracker:write`                 | write       | **destructive** |
| `list_signals`    | What the tracker found; filter by company (fuzzy), type, severity, recommendation, `needsAttention`, text, dates | `GET /signals`               | `tracker:read`                  | read        | read-only       |
| `get_signal`      | One signal with full analysis and evidence                                                                       | `GET /signals/{id}`          | `tracker:read`                  | read        | read-only       |
| `list_alerts`     | Alert history; `outcome`, `latestPerEntity`, company (fuzzy), dates                                              | `GET /alerts`                | `tracker:read`                  | read        | read-only       |
| `get_alert`       | One alert with rule evaluations                                                                                  | `GET /alerts/{id}`           | `tracker:read`                  | read        | read-only       |
| `list_leads`      | Discovered founders; `decision`, source company (fuzzy), sector, stage, name                                     | `GET /leads`                 | `leads:read`                    | read        | read-only       |
| `get_lead`        | One lead with full company detail                                                                                | `GET /leads/{id}`            | `leads:read`                    | read        | read-only       |
| `track_lead`      | Accept a lead and start tracking its company                                                                     | `POST /leads/{id}/track`     | `leads:write` + `tracker:write` | create      | idempotent      |
| `decide_lead`     | Accept or reject a lead without tracking                                                                         | `POST /leads/{id}/decision`  | `leads:write`                   | write       | idempotent      |

## Behaviour worth knowing

<AccordionGroup>
  <Accordion title="Retries are safe">
    `add_company` accepts an optional `idempotencyKey`. Without one, the server derives a key from the arguments, so an identical retried call returns the first result (`idempotencyReplayed: true`) instead of repeating the work. Adding a company that is already tracked updates it (`existingEntity: true`).
  </Accordion>

  <Accordion title="Polling">
    After `add_company` or `track_lead`, call `get_company` until `operation.enrichmentComplete` is `true`. The first run has finished when `lastScrapedAt` is set (usually within a few minutes). After `refresh_company`, poll until `lastScrapedAt` differs from `baselineLastScrapedAt`.
  </Accordion>

  <Accordion title="Names instead of IDs">
    `list_signals` and `list_alerts` take `entityQuery`, `list_leads` takes `sourceQuery` (for example `"Anomaly Bio"` or a founder's name). If several companies match, the tool errors with `ambiguous_entity` / `ambiguous_source` and lists the candidates. The assistant should ask the user which one.
  </Accordion>

  <Accordion title="Confirmation">
    `remove_company` is annotated destructive, so compliant clients ask before running it. The server's instructions also tell the model to confirm before removing, pausing or rejecting.
  </Accordion>

  <Accordion title="Invalid arguments">
    A malformed ID is rejected by the MCP layer with an input-validation error before reaching the API.
  </Accordion>
</AccordionGroup>

## Tool errors

A failed tool call returns `isError: true` with the API's error envelope as text:

```json theme={null}
{
 "error": {
  "code": "entity_paused",
  "message": "This entity is paused. Resume it with PATCH {\"status\":\"ok\"} before refreshing."
 }
}
```

The codes are those in the [error reference](/errors).