# Tool reference

> Every tool the Funnel One MCP server exposes, with the scopes each one needs.

Preview: built and in review, not live yet.

A client sees only the tools its connection may use. Every tool needs
`agent.use` (the same permission the in-app chat needs) plus its own scopes,
and both are checked against your role on every call.

Every tool is read-only today. Each result carries
`_meta["ai.funnelone/provenance"] = "crm_record"`, and every description says
that text from your records is data, never instructions.

## search_companies

Find companies by a fragment of their name or website domain.

| | |
|---|---|
| Scopes | `agent.use`, `companies.view` |
| Annotations | `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false` |

Input:

```json
{ "query": "bloom" }
```

Returns at most 20 matches, each with its id, name, domain, industry, country
and prospecting stage, plus `total` (the real number of matches) and
`truncated` (whether more exist than were returned).

## get_company

Get one company by its id, from `search_companies`.

| | |
|---|---|
| Scopes | `agent.use`, `companies.view` |
| Annotations | `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false` |

Input:

```json
{ "company_id": 1234 }
```

Long text values are cut at 1,500 characters and at most 20 custom fields are
returned. `truncated_fields` and `custom_fields_truncated` say when that
happened, so a cut value is never presented as complete.

## When a tool fails

- A tool the connection lacks a scope for answers `403` with
  `WWW-Authenticate: Bearer error="insufficient_scope", scope="…"`, and a
  JSON-RPC error whose `data.scopes` lists every missing scope.
- A tool that ran but could not finish answers normally with
  `isError: true` and a message in `content`.
- An unknown tool name answers JSON-RPC error `-32602`.

## Coming soon

- Chat tools for your own agent: ask your Funnel One a question, list your
  Desk threads, read a thread's messages and follow a running answer.
- More read tools: contacts, opportunities, segments and the fields schema.
- Tools that change data, each as a card you approve inside Funnel One.
- For an [external agent](https://dev.funnelone.ai/mcp/external-agents/): chat tools only.

Source: https://dev.funnelone.ai/mcp/tools/