Unify

View saved version →

---
name: agent-runs
description: Run Unify agent tasks with the core run_agent → poll_agent → answer_question → read_agent_results loop. Use before starting any Unify run - covers writing effective task briefs, polling cadence, relaying clarification questions, reading results, and error recovery.
---

# Running the Unify agent

Every Unify task is one lifecycle: start, poll, (maybe) answer questions, read.

## 1. Start: `run_agent({ prompt })`

Returns `{ runId, threadId, threadLink }` immediately. Write the prompt as a
brief to a skilled GTM operator who cannot see your conversation. Include:

- **Entity type and deliverable**: companies or people; inline answer or a DataTable ("return the results as a DataTable" for anything more than a couple of records).
- **Hard filters vs. intent**: exact constraints (industry, headcount, geography, funding stage, titles) separately from fuzzy persona intent ("technical buyers of data-infrastructure tooling"). Geography defaults to US, so say otherwise explicitly.
- **Scale**: target count ("20 companies", "2–3 contacts per company").
- **Budget**: if spend matters: "prefer free sources (Universal Data, CRM)" or "cap credit spend at N".
- **Approval semantics** for outreach: whether to stop at previews or the user has approved enrolling/sending. Never authorize sending unless your user explicitly did.

Pre-answer the obvious clarification dimensions above; the agent pauses to ask
when scope is ambiguous or expensive.

**Show `threadLink` as soon as the run starts.** The run happens in the
background on Unify's side, so the link is what lets the user watch it live —
intermediate steps, tool calls, and partial results stream into that thread while
you poll. Send one short message right after `run_agent` returns that says the
run is underway and includes the **bare URL** on its own line (most terminals and
plain-text clients auto-linkify a raw URL; Markdown link syntax only renders
where Markdown is supported). This is the one user-facing message to send before
a terminal status — everything else about polling stays internal.

`threadId` identifies the thread the agent ran in. Pass it back as
`run_agent({ prompt, threadId })` for a follow-up task that should build on the
same context (same thread, same link) instead of starting cold.

## 2. Poll: `poll_agent({ runId })`

Statuses: `PENDING` (keep polling), `CLARIFICATION_NEEDED`, `READY`, `ERROR`,
`NOT_FOUND`. Runs commonly take one to several minutes; poll every ~10 seconds
initially and back off toward ~30 seconds for long runs. Don't give up; complex
list-building runs can run 10+ minutes.
Treat polling as internal tool work. Do not send user-facing messages that
merely announce polling attempts, waits, cadence changes, or unchanged `PENDING`
statuses. Beyond the initial "run started, here's the link" message, only message
the user when input is required, the run reaches a terminal state, or an
actionable blocker occurs.

## 3. Clarifications: `answer_question({ runId, answers })`

On `CLARIFICATION_NEEDED`, `poll_agent` returns `questions` (up to 4, each with
2–4 options). Rules:

- Answer every question in one call, in the same order, with `question` copied
  **exactly** as returned; the server rejects mismatches.
- `answer` may be an option label or free text.
- If your conversation already contains the answer, answer directly; otherwise
  present the questions and options to your user verbatim and relay their choices.
- Response is `{ runId, alreadyResuming }`; keep polling either way. If the call
  fails with a retryable message, retry with the same answers.

## 4. Read: `read_agent_results({ runId })`

Only for `READY` or `ERROR` runs. Returns
`{ status, finalAnswer, content, errorMessage, threadLink }`.
`finalAnswer` is plain text. The result's **structured content** (`content`)
carries typed resource references with the exact IDs the loader tools require. A
DataTable reference includes `tableId` + `versionId` (both needed by
`load_datatable`), a List reference includes its `listId` (for `load_list`), and
so on. Take IDs from there rather than parsing them out of the prose.

`threadLink` is the same clickable thread URL `run_agent` returned, and comes
back for both `READY` and `ERROR` runs. Present it again after relaying results
so the user can inspect the full thread, intermediate steps, and any generated
resources in the UI.

**The result is the response; the link is only supporting context.** Never send
only the thread link or make the user open it to learn the outcome. Lead with
the substantive `finalAnswer` (or a faithful summary when it is long), include
the useful records or resource details you loaded, and state errors plainly.
Put the link last in a short, visually de-emphasized footer such as:

> Run details: <threadLink>

Keep the bare URL visible so terminals and plain-text clients can auto-link it.
In clients known to support inline HTML, `<sub>Run details: <threadLink></sub>`
is also acceptable, but do not rely on font sizing or hide the URL behind
Markdown link text.

## Errors

- "workspace does not have chat funding available" → billing gate; surface to the user.
- Rate-limit errors → wait and retry `run_agent` once; don't hammer.
- `ERROR` status → read `errorMessage`, report it plainly; a fresh, more specific brief often succeeds where a vague one failed.
- Runs are visible only to the user who created them; don't ask about runIds from other sessions or users.

View saved version →

---
name: crm
description: CRM and record management with Unify, read Salesforce/HubSpot (owners, stages, deals, custom fields, "what's in my CRM"), write CRM records, upsert companies/people into Unify, and export to Lists. Use when the user asks about CRM data, wants records saved or updated, or wants a result set exported to a List or their CRM.
---

# CRM and records

CRM briefs go through `run_agent` (see `agent-runs`). Unify connects to Salesforce
and HubSpot and also keeps its own canonical company/person records and Lists.

> **Deterministic alternative.** If the user wants exact, repeatable reads/writes
> of their **Unify objects and records** — not a natural-language task — the
> public API exposes direct tools: `list_objects` / `get_object` and their
> attributes, `get_object_record` / `create_object_record` / `update_object_record`
> / `upsert_object_record` / `find_unique_object_record` / `delete_object_record`,
> and the async **Bulk API** tools for exporting or syncing many records at once.
> The agent briefs below remain the path for complex workflows and anything
> needing reasoning.

## Reads (free, live)

If the workspace has a connected CRM, briefs like these work directly:

- "Which of these accounts exist in our Salesforce, and who owns them?"
- "Open opportunities past stage 2 closing this quarter."
- "What picklist values does the deal-stage field have?"
- Joins with Unify signals are free too: "CRM accounts with website intent this
  month that have no open opportunity."

## Writes

CRM writes are available on Unify's Business plan and behave as
search-then-create-or-update (matching by domain, email, or record ID; the agent
handles dedupe). Rules:

- Log activities too: "log this call/email against the contact in HubSpot."

## Unify records and Lists

- **Save to Unify**: "save these companies/people as Unify records." Companies
  need a domain; people need an email. The agent previews EXISTING/NEW/INVALID
  classifications before committing.
- **Lists**: named, saved collections in the Unify app. "Export this DataTable to
  a List called Q3 targets" (the export previews counts: new, already in list,
  duplicates, invalid) before committing. Say whether creating brand-new records
  is allowed or the export should only link existing ones.
- **Personas**: tenant-level title sets. "Update our 'economic buyer' persona to
  include VP Finance titles" is a valid brief; edits are versioned and reversible.

View saved version →

---
name: data-tables
description: "Unify DataTables: page through the rows of result tables produced by Unify agent runs with load_datatable. Use when a run's final answer references a DataTable or table ID and you need the actual rows, columns, or metadata."
---

# Unify DataTables

DataTables are the durable artifact of list-building and enrichment runs. When
`read_agent_results` references a table, fetch it directly; don't start another
run just to see rows you already have.

> **Not the same as Bulk API results.** A DataTable is an **agent run** artifact,
> paged here with `load_datatable` (cursor-based, pinned to a `versionId`). The
> public **Bulk API** returns query-job results paged by `get_<resource>_query_job_results`
> (`page` / `page_size`). If you have a `job_id` rather than a `tableId` +
> `versionId`, use the public Bulk API tools, not this skill.

## `load_datatable({ tableId, versionId, limit?, cursor? })`

- `tableId` + `versionId`: **both required**; take them from the DataTable
  reference in the run result's structured content. Loads pin an exact table
  version, so pages are consistent even if the table keeps changing.
- `limit`: rows per page, default 100.
- `cursor`: pass the previous page's `nextCursor` to continue; it is bound to
  the same table and version.

Returns `{ tableId, versionId, metadata, columns, rows, nextCursor }`. Each row
is a map of column key → JSON value. `nextCursor: null` means you have the last
page. `metadata.currentWorkingVersionId` tells you whether a newer working
version exists than the one you loaded.

## Paging pattern

1. First call with `tableId` + `versionId` (and a smaller `limit` if you only need a sample).
2. Loop while `nextCursor` is non-null, passing it as `cursor`.
3. For large tables, ask your user before pulling everything; summarize from the
   first page plus `metadata` row counts when that answers the question.

## Notes

- Tables are visible only to the user who owns them in the workspace; "DataTable
  not found" usually means a table from another user or session, not a bug.
  "DataTable version not found" means a stale `versionId`; re-read the run
  result (or ask the agent for the current version).
- "Invalid DataTable cursor" → restart paging from the first page.
- To add data to an existing table (more columns, more rows), start a new
  `run_agent` brief that names the table ID and describes the addition.

View saved version →

---
name: discovery
description: Discovery with Unify, building lists of companies or people from criteria - ICP filters, personas, lookalikes, hiring signals, technographics, local businesses, funding stage. Use when the user wants to find prospects, build a target-account or contact list, expand TAM, or ask "who should I sell to".
---

# Discovery: building lists

Discovery briefs go through `run_agent` (see `agent-runs` for the loop). The Unify
agent routes to sources itself; your job is a precise brief.

## Brief anatomy

State, in order:

1. **Entity type**: companies, people, or companies-then-people ("find 20 fintech
   companies, then 2–3 engineering leaders at each").
2. **Hard filters** (exact, verifiable): industry, headcount range, revenue,
   geography (defaults to US, always state it), funding stage, tech stack, hiring
   status.
3. **Semantic intent** (fuzzy, persona-level): "developer-tools buyers",
   "operators who own retention", natural-language titles. Unify's semantic search
   over its proprietary dataset handles these well; don't flatten them into rigid
   title lists yourself.
4. **Target count** and **deliverable**: "return N results as a DataTable".
5. **Exclusions**: existing customers, competitors, records already in the CRM or
   a List ("exclude companies already in our Salesforce").

## What Unify is good at (helps you scope)

- **Universal Data** (free, proprietary): identity, domain, LinkedIn, industry, geo,
  headcount, revenue, titles, work history, education (for 1.1B+ people and 65M+
  companies). Prefer briefs answerable here when budget matters.
- **Paid vendor signals** (credits per record): lookalike companies, hiring/job
  postings, technographics, ecommerce/store data, local businesses (Google
  Maps/Yelp), funding and venture data, web traffic/SEO, social buying signals.
- **Weak/absent**: normalized seniority levels, live ad spend detail; expect the
  agent to approximate or ask.

## Patterns

- **Scout before scale**: for big lists, first ask for 5–10 results to validate
  criteria with your user, then a follow-up run for the full list.
- **Lookalikes**: "find companies similar to acme.com, stripe.com" is a first-class
  ask.
- **Existing-data first**: "which of our CRM accounts match X" is a discovery brief
  too. Unify joins CRM with engagement/intent signals for free.
- Results land in a DataTable; page it with `load_datatable` and present a readable
  sample, not the whole dump.

View saved version →

---
name: enrichment
description: Enrichment with Unify; find work emails, phone numbers, firmographics, funding, technographics, job postings, and fresh employment data for known companies or people. Use when the user has specific entities (names, domains, LinkedIn URLs, a DataTable, CRM records) and needs more data on them, including email verification before outreach.
---

# Enrichment: adding data to known entities

Enrichment briefs go through `run_agent` (see `agent-runs`). Unify runs managed
provider waterfalls internally. Never ask it to use a specific email vendor;
describe the outcome.

## Identifying entities in a brief

Give the strongest identity keys you have, per entity:

- Person: LinkedIn URL/slug, or first + last name + company domain, or email.
- Company: domain (best), or LinkedIn URL, or exact name + disambiguator.
- Bulk: reference an existing DataTable by ID ("enrich every row of table <uuid>
  with work emails") or paste a short list.

## What to ask for

- **Work emails**: found via a managed multi-provider waterfall and returned with
  validation status. Only `valid` (and cautiously `catch-all`) emails are safe to
  send to; ask for "verified emails" when outreach is the goal. Personal email
  coverage is not offered.
- **Phone numbers**: mobile/direct dials via a phone waterfall; lower hit rates
  than email. Set expectations with the user.
- **Company data**: firmographics come free from Universal Data first; funding
  rounds, job postings/hiring intent, technographics (web-detectable and
  backend/inferred), news, ad activity, web traffic come from paid vendors.
- **Employment validation**: "confirm these contacts still work at these
  companies" (checks current employer and can refresh stale LinkedIn data).

## Cost control

Contact-data and vendor enrichment cost credits per record. In bulk briefs, state
a cap: "cap credit spend at N", "email only, skip phones", or "free sources only,
mark the gaps". Expect the agent to pause with a clarification question when a
brief implies large spend; answer or relay it (see `agent-runs`).

## Patterns

- **Enrich-then-engage**: enrich and verify emails *before* any outreach brief;
  the Unify agent itself refuses to write outreach on thin prospect context.
- **Scout before scale**: for 100+ rows, enrich 5 first, review the hit rate with
  the user, then run the remainder.
- Results append columns to a DataTable; page with `load_datatable`.

View saved version →

---
name: outreach
description: Outreach with Unify, create email sequences, generate per-prospect copy previews, enroll prospects, and manage rep tasks (calls, LinkedIn touches, to-dos). Use when the user wants to email prospects, write outbound copy, start or edit a sequence, check what's in flight, or work their task queue.
---

# Outreach: sequences and tasks

Outreach briefs go through `run_agent` (see `agent-runs`). Sequences have a strict
safety lifecycle. Use its vocabulary precisely with both the agent and your user.

> **Deterministic alternative.** The public API exposes direct tools for
> inspecting and managing existing sequences, enrollments, and tasks without the
> agent: `list_sequences` / `retrieve_sequence` / `list_sequence_steps`,
> `list_sequence_enrollments` / `create_sequence_enrollment` /
> `pause_sequence_enrollment` / `resume_sequence_enrollment`, and
> `list_tasks` / `create_task` / `complete_task` / `update_task`. To export large
> volumes of enrollments, enrollment steps, or tasks, use the async **Bulk API**
> tools. All require an API-key connection (`X-API-Key`).

## Sequence lifecycle (safety-critical)

1. **Scaffold**, the reusable structure: steps (emails, calls, LinkedIn touches),
   delays, and copy prompts. Creating a scaffold sends nothing.
2. **Preview**: per-prospect generated copy. Still sends nothing.
3. **Approved**: previews are ready to be enrolled.
4. **Enrolled**: prospects are in the sequence and email actually sends.

Never tell your user someone is "enrolled", "started", or that anything "sent"
before step 4. Default briefs should end at previews: "create previews for these
10 people and stop for my review."

## Writing sequence briefs

Include: who (people, by DataTable ID, List, or identities), the offer/value
proposition and any proof points, desired tone and sender voice, step count and
channel mix (2–4 steps typical: email + LinkedIn + call), cadence ("3 days
between steps"), and the sending mailbox if the user has a preference. The Unify
agent is the copywriter: give it real context (why now, what triggered this,
what the prospect cares about), not template text. If prospect context is thin,
it will pause and ask to enrich first; that gate is correct. Relay it.

Per-prospect copy edits ("make the email to Jane mention their Series B") edit
that preview only; scaffold edits propagate to everyone. Say which you mean.

## Checking state

"What sequences do we have?", "who replied?", "how is sequence X performing?",
"which previews are waiting on my approval?" are all valid briefs.

## Tasks

Reps' one-off manual to-dos: calls, LinkedIn profile views/connects/messages,
action items. Useful briefs:

- "What tasks are due today?" / "what's overdue for me this week?" (defaults to
  the signed-in user; name a teammate to scope differently).
- "Create a task to call Jane Doe at Acme on Friday" (self-assigned, manual types
  only).
- "Complete/skip my ready LinkedIn tasks for Acme." Email-reply tasks are
  completed by actually replying, not by marking done.

## Mailbox voice profile

Unify can analyze a mailbox's sent mail to build a **voice profile** that
shapes generated copy. When a run kicks that analysis off, check progress with
`load_mailbox_voice_profile({ connectedMailboxId })` (ID from the run result's
structured content), poll only while `isTerminal` is false; it's read-only.

View saved version →

---
name: unify
description: Unify; start here. Directory for working with Unify, the go-to-market platform for finding and engaging buyers. Maps every Unify skill, agent-runs (run any GTM task through the Unify agent and manage the poll/answer loop), data-tables (page through result rows), discovery (build company and people lists), enrichment (find emails, phones, firmographics), outreach (sequences, tasks, outbound copy), and crm (Salesforce/HubSpot reads and writes). Read this first to answer "what can I do with Unify?"
---

# Unify

Unify is a go-to-market platform for sales reps: find companies and people, enrich
contact data, and engage prospects with email sequences and tasks, driven by
natural language.

## Interaction model

The Unify MCP server exposes two tool families.

**1. The hosted GTM agent** — most substantive work is a natural-language task
delegated to Unify's agent, which has its own data sources, skills, and safety
gates; loader tools then read the artifacts a run references:

| Tool                         | Purpose                                                                                            |
| ---------------------------- | -------------------------------------------------------------------------------------------------- |
| `run_agent`                  | Start the Unify agent on a natural-language task. Returns a `runId`.                               |
| `poll_agent`                 | Check a run: `PENDING`, `CLARIFICATION_NEEDED`, `READY`, `ERROR`.                                  |
| `answer_question`            | Answer clarifying questions and resume a paused run.                                               |
| `read_agent_results`         | Read a terminal run's answer. Its structured content carries the exact IDs the loaders below need. |
| `load_datatable`             | Page through the rows of a DataTable version a run produced.                                       |
| `load_list`                  | Metadata + member count for a List (no rows).                                                      |
| `load_mailbox_voice_profile` | Read-only state of a mailbox's voice-profile analysis.                                             |
| `load_user_general_context`  | Read an exact version of the user's saved company profile/context.                                 |

You are the briefing layer: write clear task briefs, relay clarifying questions to
your user, and fetch results. Read `agent-runs` before your first run.

**2. The public API** — deterministic REST endpoints (Data, Sequences, Tasks),
each exposed as a `verb_resource` MCP tool: CRUD on objects, object records,
object attributes, tasks, sequences, and sequence enrollments, plus the async
**Bulk API** query jobs for large exports. Use these when the user wants an exact,
repeatable read/write of data they already have rather than a reasoning task.

## Which skill for what

| You want to...                                                  | Skill                                     |
| --------------------------------------------------------------- | ----------------------------------------- |
| Install the plugin or fix auth                                  | [Getting started](https://github.com/unifygtm/agent-plugins/blob/main/GETTING_STARTED.md) |
| Run any Unify task and manage the run lifecycle                 | `agent-runs`                              |
| Build a list of companies or people                             | `discovery`                               |
| Find emails, phones, or company data for known entities         | `enrichment`                              |
| Write and send outreach (sequences), manage rep tasks           | `outreach`                                |
| Read or write Salesforce/HubSpot, save records, export lists    | `crm`                                     |
| Pull rows from a result table                                   | `data-tables`                             |
| Export/sync large datasets deterministically via the public API | Use the public Bulk API tools             |

## Vocabulary (use these terms in briefs and with users)

- **DataTable**: the durable artifact for any list-building or enrichment run; page it with `load_datatable`.
- **List**: a saved, named collection of records in the Unify app (distinct from a DataTable).
- **Sequence**: multi-step outreach. A **scaffold** is the reusable structure; a **preview** is generated per-prospect copy that does NOT send; email sends only after previews are approved and **enrolled**.
- **Persona**: a tenant-level set of job titles defining a buyer role.
- **Tasks**: one-off manual to-dos for a rep (calls, LinkedIn touches, action items).

## Cost model

Unify's proprietary **Universal Data** (1.1B+ people, 65M+ companies) and connected
**CRM** reads are free. Third-party data vendors charge credits per record returned.
The agent already minimizes spend, but state a budget in your brief when the user
cares ("cheapest sources only", "cap at 100 records", "up to N credits").

## Behavior

- Narrate briefly what you asked Unify to do and summarize outcomes; don't dump raw JSON.
- Runs are user- and workspace-scoped to the OAuth identity; you can only see runs and tables you created.
- A successfully connected Unify MCP server means authentication and workspace authorization are already established for the current session. Do not ask the user to confirm access, credentials, OAuth, or authorization before using available tools. If a tool returns an auth or connection error, direct the user to reconnect in the Unify app.