Tools Reference

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.

Tool names are plain snake_case (company, templates) - there is no pgai_ prefix.

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`.

Do not use canvas_list or sequence_list for step 1 - those list already generated content, not recipes.

`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.

Overview

Endpoint Guides

MCP Server

Async operations

Content generation (4-step flow)

`templates`

`template_generate`

`canvas_get`

`sequence_get`

`canvas_list`

`sequence_list`

`canvas_update`

Company research

`company`

`search`

`jobs_search`

Accounts

`accounts`

`companies_search`

`companies_add`

Contacts

`contact_search`

`contact`

`create_contact`

`contact_find_email_phone`

Operations

`get_operation_status`

Agent (advanced)

`agent_message_send`

`agent_sessions_create`

`agent_sessions_list`

`agent_sessions_get`

Permissions

Not available via MCP (yet)

​Async operations

​Content generation (4-step flow)

​templates

​template_generate

​canvas_get

​sequence_get

​canvas_list

​sequence_list

​canvas_update

​Company research

​company

​search

​jobs_search

​Accounts

​accounts

​companies_search

​companies_add

​Contacts

​contact_search

​contact

​create_contact

​contact_find_email_phone

​Operations

​get_operation_status

​Agent (advanced)

​agent_message_send

​agent_sessions_create

​agent_sessions_list

​agent_sessions_get

​Permissions

​Not available via MCP (yet)

Async operations

Content generation (4-step flow)

`templates`

`template_generate`

`canvas_get`

`sequence_get`

`canvas_list`

`sequence_list`

`canvas_update`

Company research

`company`

`search`

`jobs_search`

Accounts

`accounts`

`companies_search`

`companies_add`

Contacts

`contact_search`

`contact`

`create_contact`

`contact_find_email_phone`

Operations

`get_operation_status`

Agent (advanced)

`agent_message_send`

`agent_sessions_create`

`agent_sessions_list`

`agent_sessions_get`

Permissions

Not available via MCP (yet)