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

# Tools Reference

> Complete reference for all PG:AI MCP tools

PG:AI exposes **22 tools** through MCP. Your AI client selects tools automatically - you normally interact in natural language. This page documents names, behaviour, and parameters for builders and power users.

<Info>
  Tool names are plain snake\_case (`company`, `templates`) - there is no `pgai_` prefix.
</Info>

## Async operations

Several tools start background jobs and return an `operation_id`:

| Tool                       | Then poll with         | Then read result with                |
| -------------------------- | ---------------------- | ------------------------------------ |
| `template_generate`        | `get_operation_status` | `canvas_get` or `sequence_get`       |
| `companies_add`            | `get_operation_status` | `accounts` or `company`              |
| `contact_find_email_phone` | `get_operation_status` | `contact`                            |
| `agent_message_send`       | `get_operation_status` | `agent_sessions_get` (if applicable) |

Poll every \~2 seconds while `status` is `queued` or `running`. Status values: `queued`, `running`, `completed`, `failed`, `cancelled`.

***

## Content generation (4-step flow)

Use this flow for documents, emails, call scripts, analysis, and sequences.

```
templates → template_generate → get_operation_status → canvas_get | sequence_get
  (STEP 1)      (STEP 2)            (STEP 3)              (STEP 4)
```

| Step | Tool                   | Purpose                                                                                                               |
| ---- | ---------------------- | --------------------------------------------------------------------------------------------------------------------- |
| 1    | `templates`            | List **recipes** (not finished content). Returns `template_id`, `template_kind` (`canvas` \| `sequence`), `produces`. |
| 2    | `template_generate`    | Start generation for a company. Requires `template_id`, `template_kind`, and `company` (name, domain, or UUID).       |
| 3    | `get_operation_status` | Poll with `operation_id` until `completed`.                                                                           |
| 4a   | `canvas_get`           | Read a single deliverable when `template_kind` was `canvas`. Use `format: "text"` for readable prose.                 |
| 4b   | `sequence_get`         | Read steps when `template_kind` was `sequence`.                                                                       |

<Warning>
  Do not use `canvas_list` or `sequence_list` for step 1 - those list **already generated** content, not recipes.
</Warning>

### `templates`

List generation recipes (workspace + PG:AI templates).

| Parameter  | Type                                                               | Default | Description                |
| ---------- | ------------------------------------------------------------------ | ------- | -------------------------- |
| `filter`   | `org` \| `pgai` \| `all`                                           | `all`   | Whose templates to include |
| `category` | string                                                             | -       | Filter by category         |
| `produces` | `document` \| `email` \| `call_script` \| `analysis` \| `sequence` | -       | Filter by output type      |
| `q`        | string                                                             | -       | Search template titles     |
| `page`     | number                                                             | 1       | Page number                |
| `per_page` | number                                                             | 50      | Page size                  |

### `template_generate`

Start async generation from a template.

| Parameter          | Type                   | Required | Description                                             |
| ------------------ | ---------------------- | -------- | ------------------------------------------------------- |
| `template_id`      | string                 | Yes      | From `templates`                                        |
| `template_kind`    | `canvas` \| `sequence` | Yes      | Must match the row from `templates`                     |
| `company`          | string                 | Yes\*    | Company name, domain, or UUID                           |
| `company_name`     | string                 | Yes\*    | Alias for `company`                                     |
| `company_id`       | string                 | Yes\*    | Company UUID                                            |
| `contact_id`       | string                 | No       | Personalise for a contact                               |
| `persona_id`       | string                 | No       | Persona for sequence generation                         |
| `inputs`           | object                 | No       | Canvas template-specific fields (topic, audience, etc.) |
| `user_instruction` | string                 | No       | Free-text context or answers to planning questions      |

\* One of `company`, `company_name`, or `company_id` is required.

### `canvas_get`

Read one finished canvas (document, email, call script, analysis).

| Parameter   | Type             | Default | Description                                                        |
| ----------- | ---------------- | ------- | ------------------------------------------------------------------ |
| `canvas_id` | string           | Yes     | From `template_generate`, `get_operation_status`, or `canvas_list` |
| `format`    | `json` \| `text` | `json`  | `text` returns LLM-friendly plain text                             |

### `sequence_get`

Read one finished sequence (metadata + steps).

| Parameter     | Type   | Required | Description                                                          |
| ------------- | ------ | -------- | -------------------------------------------------------------------- |
| `sequence_id` | string | Yes      | From `template_generate`, `get_operation_status`, or `sequence_list` |

### `canvas_list`

Browse **already generated** canvases.

| Parameter                                 | Type   | Description                                                                |
| ----------------------------------------- | ------ | -------------------------------------------------------------------------- |
| `company` / `company_name` / `company_id` | string | Scope to one company                                                       |
| `contact_id`                              | string | Filter by contact                                                          |
| `content_type`                            | enum   | `notes`, `email`, `call_script`, `document`, `value_pyramid`, `three_whys` |
| `q`                                       | string | Search                                                                     |
| `page`, `per_page`                        | number | Pagination                                                                 |

### `sequence_list`

Browse **already generated** sequences.

| Parameter                                 | Type   | Description                                          |
| ----------------------------------------- | ------ | ---------------------------------------------------- |
| `company` / `company_name` / `company_id` | string | Scope to one company                                 |
| `contact_id`, `persona_id`                | string | Filters                                              |
| `status`                                  | enum   | `draft`, `active`, `paused`, `completed`, `archived` |
| `channel`                                 | string | e.g. `email`, `call`                                 |
| `q`, `sort_by`, `sort_order`              |        | Search and sort                                      |
| `page`, `per_page`                        | number | Pagination                                           |

### `canvas_update`

Update an existing canvas (title, body, sections, tags). At least one field besides `canvas_id` is required.

***

## Company research

### `company`

Rich company profile for one **tracked** company.

| Parameter                                 | Type      | Default        | Description                                 |
| ----------------------------------------- | --------- | -------------- | ------------------------------------------- |
| `company` / `company_name` / `company_id` | string    | -              | Name, domain, or UUID (fuzzy match on name) |
| `include`                                 | string\[] | `["overview"]` | Profile sections to return                  |
| `exclude`                                 | string\[] | -              | Sections to omit after `include`            |
| `sources`                                 | boolean   | -              | Include source citations                    |

**Include sections:** `overview`, `key_executives`, `divisions`, `geographical_operations`, `swot_analysis`, `competitors`, `industry_insights`, `strategic_priorities`, `digital_strategies`, `risks`, `goals`, `insights_scores`, `events`, `value_pyramid`, `three_whys`, `discovery_questions`, `how_they_make_money`, `how_they_lose_money`, `custom_insights`, `employee_groups`, `favourite_technologies_count`, `territory_custom_scores`, `content`, `canvas`, or `full` for everything.

### `search`

**Semantic** search across PG:AI vector indexes (not keyword grep).

| Parameter              | Type                          | Required               | Description                                                          |
| ---------------------- | ----------------------------- | ---------------------- | -------------------------------------------------------------------- |
| `query`                | string                        | Yes                    | Search text                                                          |
| `scope`                | `organisation` \| `companies` | Yes                    | `organisation` = all tracked accounts; `companies` = listed IDs only |
| `company_ids`          | string\[]                     | When scope=`companies` | Company UUIDs                                                        |
| `sources`              | string\[]                     | No                     | Limit indexes (see below)                                            |
| `per_source`           | number                        | 25                     | Max hits per source (max 50)                                         |
| `page`                 | number                        | 1                      | Page                                                                 |
| `date_from`, `date_to` | string                        | No                     | ISO date bounds                                                      |

**Sources:** `public_docs`, `web_pages`, `organisation_company_docs`, `organisation_docs`, `pgai_insights`, `contacts`, `technologies`, `conversations`, `company_content`, `company_jobs`.

### `jobs_search`

Search job postings across tracked companies.

| Parameter                                 | Type   | Description                                         |
| ----------------------------------------- | ------ | --------------------------------------------------- |
| `company` / `company_name` / `company_id` | string | Scope to one company                                |
| `q`                                       | string | Search title and description                        |
| `seniority`                               | enum   | `c_level`, `staff`, `senior`, `junior`, `mid_level` |
| `country_code`                            | string | ISO 2-letter code                                   |
| `page`, `per_page`                        | number | Pagination                                          |

***

## Accounts

### `accounts`

List companies **already in your workspace**.

| Parameter                   | Type            | Default | Description                               |
| --------------------------- | --------------- | ------- | ----------------------------------------- |
| `scope`                     | `user` \| `org` | `user`  | `user` = your territory; `org` = org-wide |
| `query` / `company_name`    | string          | -       | Search name or domain                     |
| `industry`, `country`, etc. |                 |         | Additional filters                        |
| `page`, `per_page`          | number          | 1, 25   | Pagination                                |

### `companies_search`

Discover companies **globally** (workspace + external directory). Returns `is_in_org_accounts` and `is_in_user_accounts` flags.

| Parameter                           | Type    | Description                               |
| ----------------------------------- | ------- | ----------------------------------------- |
| `q`                                 | string  | Company name or domain                    |
| `industry_ids`, `country_ids`, etc. | arrays  | Filters                                   |
| `include_external`                  | boolean | Include external directory (default true) |
| `page`, `per_page`                  | number  | Pagination                                |

### `companies_add`

Add companies to the workspace (max **5 per call**). Async and **credit-gated** - poll `get_operation_status`. HTTP 402 means credits exhausted.

| Parameter                                                          | Type  | Description                   |
| ------------------------------------------------------------------ | ----- | ----------------------------- |
| `company` / `company_name` / `website` / `domain` / `companies_id` |       | Single company                |
| `companies`                                                        | array | Up to 5 companies in one call |

***

## Contacts

### `contact_search`

Search contacts in your tracked workspace.

| Parameter                                    | Type   | Description                                           |
| -------------------------------------------- | ------ | ----------------------------------------------------- |
| `search_definition`                          | object | SearchDefinition v1 (`entity: "contact"`) - preferred |
| `company` / `company_ids`                    |        | Scope to company(ies)                                 |
| `titles`, `personas`, `regions`, `seniority` |        | Legacy filters (still supported)                      |
| `max_contacts`, `page`, `per_page`           | number | Limits                                                |

### `contact`

Full contact record by UUID. Use `contact_search` first to find IDs.

| Parameter    | Type   | Required |
| ------------ | ------ | -------- |
| `contact_id` | string | Yes      |

### `create_contact`

Save a contact to a tracked company. Use `companies_add` first if the company is not tracked.

| Parameter                                 | Type   | Required     |
| ----------------------------------------- | ------ | ------------ |
| `company` / `company_name` / `company_id` | string | Yes          |
| `contact_name` or `contact_email`         | string | Yes (one of) |
| `contact_title`, `contact_linkedin`       | string | No           |

### `contact_find_email_phone`

Enrich email and/or phone for an existing contact. Async and **credit-gated**.

| Parameter    | Type                                     | Default            |
| ------------ | ---------------------------------------- | ------------------ |
| `contact_id` | string                                   | Required           |
| `type`       | `email` \| `phone` \| `email_and_mobile` | `email_and_mobile` |

***

## Operations

### `get_operation_status`

Poll any async job by `operation_id`.

| Parameter      | Type   | Required |
| -------------- | ------ | -------- |
| `operation_id` | string | Yes      |

***

## Agent (advanced)

These tools talk to the full PG:AI agent (chat, plan, sessions). They are optional - most sellers use `template_generate` for content instead.

### `agent_message_send`

Send a message to the agent queue. Returns `operation_id`.

| Parameter                                 | Type                        | Description                                  |
| ----------------------------------------- | --------------------------- | -------------------------------------------- |
| `message`                                 | string                      | User message                                 |
| `session_id`                              | string                      | Continue existing session                    |
| `company` / `company_name` / `company_id` | string                      | Company-scoped agent                         |
| `mode`                                    | `ask` \| `plan` \| `studio` | Workspace mode (ignored when company is set) |

### `agent_sessions_create`

Create a session (`chat`, `plan`, `document`, `email`, `workspace`, `project`, `canvas_settings`).

### `agent_sessions_list`

List sessions with optional company filter.

### `agent_sessions_get`

Fetch one session (metadata + transcript) by `session_id`.

***

## Permissions

| Scope       | Allows                                                                     |
| ----------- | -------------------------------------------------------------------------- |
| `mcp:read`  | Read tools (`company`, `search`, `accounts`, `templates`, etc.)            |
| `mcp:write` | Write tools (`create_contact`, `companies_add`, `template_generate`, etc.) |

API keys are issued with appropriate scopes in Settings. OAuth users receive scopes from their PG:AI account.

***

## Not available via MCP (yet)

The following exist in the PG:AI app but are **not** exposed as MCP tools today:

* Monitoring agents and alert configuration
* Territory admin and scoring configuration

If you need REST access to these areas, use the [PG:AI API](https://api.getpg.ai).