# Tools reference

Tandem's MCP server exposes 28 tools to agents, plus 6 that only signed-in people can use. The same operations are available over the REST API at `POST /v1/ops/<name>`, with the same inputs and results.

An agent only sees the tools its permissions allow: a read-only connection never even lists the write tools. Every tool's description is written for a model choosing between tools, and is reproduced here exactly as the server sends it.

## Orient and read

Learn the workspace's shape, find records and read them with their context.

| Tool | Kind | Scope | What it does |
| --- | --- | --- | --- |
| [`describe_schema`](/docs/tools/describe_schema) | read | `crm:read` | Describe the record types, fields, deal stages and activity types in this workspace. |
| [`search`](/docs/tools/search) | read | `crm:read` | Find companies, people and deals by name, domain, email or title. |
| [`list_records`](/docs/tools/list_records) | read | `crm:read` | List companies, people or deals, most recently changed first, with who changed each one last. |
| [`get_record`](/docs/tools/get_record) | read | `crm:read` | Get one company, person or deal with the context you need to act on it: related people, deals and company, the 10 most recent activities, and who changed which fields recently. |
| [`get_pipeline`](/docs/tools/get_pipeline) | read | `crm:read` | The deal pipeline at a glance: every open and closed deal grouped by stage, with counts and totals per stage. |
| [`list_changes`](/docs/tools/list_changes) | read | `crm:read` | Read the change feed: every write in this workspace, with who made it and which fields changed. |

## Companies and people

Create or update records without duplicates, and fill gaps from websites and your own tools.

| Tool | Kind | Scope | What it does |
| --- | --- | --- | --- |
| [`upsert_company`](/docs/tools/upsert_company) | write | `crm:write` | Create a company, or update it if one with the same domain already exists. |
| [`enrich_company`](/docs/tools/enrich_company) | write | `crm:write` | Fill logo, description and social links from a company's own website. |
| [`upsert_person`](/docs/tools/upsert_person) | write | `crm:write` | Create a person (contact), or update them if one with the same email already exists. |
| [`list_enrichment_queue`](/docs/tools/list_enrichment_queue) | read | `crm:read` | Find incomplete people and companies or stale website enrichment. |

## Deals

Open deals, move them through stages and record who is involved.

| Tool | Kind | Scope | What it does |
| --- | --- | --- | --- |
| [`create_deal`](/docs/tools/create_deal) | write | `crm:write` | Create a deal (opportunity) in the pipeline. |
| [`update_deal`](/docs/tools/update_deal) | write | `crm:write` | Update a deal: move it to another stage, change its amount, rename it, or set custom fields. |
| [`set_deal_contact`](/docs/tools/set_deal_contact) | write | `crm:write` | Add a person to a deal, or change their role on it: who the champion is, who decides, who signs. |
| [`remove_deal_contact`](/docs/tools/remove_deal_contact) | write | `crm:write` | Take a person off a deal. |

## Activity and tasks

Log what happened and book what happens next.

| Tool | Kind | Scope | What it does |
| --- | --- | --- | --- |
| [`log_activity`](/docs/tools/log_activity) | write | `crm:write` | Record a note, email, call or meeting against a company, person or deal. |
| [`create_task`](/docs/tools/create_task) | write | `crm:write` | Book a next step, optionally linked to one record and a signal. |
| [`update_task`](/docs/tools/update_task) | write | `crm:write` | Change only supplied task fields. |
| [`complete_task`](/docs/tools/complete_task) | write | `crm:write` | Complete a task once; an optional outcome also logs a note on its linked record in the same transaction. |
| [`list_tasks`](/docs/tools/list_tasks) | read | `crm:read` | Read next steps, overdue first and undated last. |

## Buying signals

Record evidence that an account may buy now, ranked by timing and strength.

| Tool | Kind | Scope | What it does |
| --- | --- | --- | --- |
| [`record_signal`](/docs/tools/record_signal) | write | `crm:write` | Record an observed buying signal with a one-line why-now and evidence URL. |
| [`list_signals`](/docs/tools/list_signals) | read | `crm:read` | Rank buying signals by timing × distinct signal types on the account. |
| [`update_signal`](/docs/tools/update_signal) | write | `crm:write` | Dismiss a signal or mark it converted after creating a deal. |
| [`convert_signal`](/docs/tools/convert_signal) | write | `crm:write` (people only) | Create a deal for a signal's company and mark it converted atomically. |

## Suggestions

Propose a change for a person to approve instead of making it.

| Tool | Kind | Scope | What it does |
| --- | --- | --- | --- |
| [`suggest_change`](/docs/tools/suggest_change) | write | `crm:suggest` | Propose a change for a person to approve instead of making it. |
| [`list_suggestions`](/docs/tools/list_suggestions) | read | `crm:read` | List proposed changes and whether they were approved or rejected. |
| [`review_suggestion`](/docs/tools/review_suggestion) | write | `crm:write` (people only) | Approve or reject a suggested change. |

## Custom fields

Typed fields of your own on companies, people and deals.

| Tool | Kind | Scope | What it does |
| --- | --- | --- | --- |
| [`list_fields`](/docs/tools/list_fields) | read | `crm:read` (people only) | The custom fields defined for companies, people and deals. |
| [`define_field`](/docs/tools/define_field) | write | `crm:write` (people only) | Add a custom field to companies, people or deals, or change an existing one's label, options or description. |
| [`archive_field`](/docs/tools/archive_field) | write | `crm:write` (people only) | Hide a custom field. |
| [`set_custom_fields`](/docs/tools/set_custom_fields) | write | `crm:write` | Set custom field values on one company, person or deal by id. |

## Do-not-contact

Emails and domains nobody may enrich or contact.

| Tool | Kind | Scope | What it does |
| --- | --- | --- | --- |
| [`add_suppression`](/docs/tools/add_suppression) | write | `crm:write` | Prevent outreach to an email or domain, including when someone asks not to be contacted. |
| [`remove_suppression`](/docs/tools/remove_suppression) | write | `crm:delete` (people only) | Remove a do-not-contact entry. |
| [`list_suppressions`](/docs/tools/list_suppressions) | read | `crm:read` | Read the do-not-contact list before enriching contacts or preparing outreach. |

## Deleting

Soft-delete records; admins can restore them.

| Tool | Kind | Scope | What it does |
| --- | --- | --- | --- |
| [`delete_record`](/docs/tools/delete_record) | write | `crm:delete` | Soft-delete a company, person or deal. |