Compelling

View saved version →

---
name: build-tam-list
description: "Find target companies and build B2B prospect lists by location, industry and custom customer criteria. Use for new company discovery or TAM sourcing, across the user’s chosen markets and company segments (Firmenrecherche, Zielkundenliste). Reading an existing list or explaining prospecting concepts does not require sourcing."
---

# Find target companies in Compelling

Source companies that match the user's customer criteria into a fresh Compelling list.

For DACH requests, resolve DACH to Germany, Austria and Switzerland. Research can cover
Mittelstand, industrial companies, consultancies and IT service providers; preserve the user's
actual geography and segment, including markets outside DACH. Keep custom criteria such as
SAP usage, ISO 13485 certification or hiring activity explicit and distinguish required
criteria from optional signals. Do not treat missing evidence as a confirmed match.

## Workflow

1. **Confirm the workspace** with `compelling_get_workspace` and tell the user which workspace you are operating in before touching data.
2. **Mint a fresh list** with `compelling_create_list` — never source into an existing list unless the user explicitly asks. Share the returned link so the user can open the list in Compelling.
3. **Clarify the TAM definition** before spending credits. You need:
   - a natural-language `search_prompt` (e.g. "Machinery manufacturers in Germany, 100-500 employees, that use SAP")
   - at least one per-company match `criteria` (each becomes a checkable column, e.g. "has a mobile app", "sells to enterprises")
   - a `target_size` (how many fully-matched companies the user wants, max 500)
4. **Offer a cost preview** with `compelling_estimate_credits(action='find_companies')` — sourcing costs 5 credits + criteria cost per company. Ask whether the user wants the estimate; do not price every run automatically.
5. **Start sourcing** with `compelling_find_companies`. It runs asynchronously.
6. **Wait server-side, don't busy-poll**: pass `wait_seconds` on the call, or check `compelling_find_companies_status` with `wait_seconds` up to 60 — one long-poll call instead of sleeping and retrying.
7. **Read results** with `compelling_read_list(record_type='accounts')` — that is ground truth, counters in status responses settle a few seconds late.

## Pitfalls

- `prompt_ambiguous` status means the search prompt was too broad — refine it with the user and restart rather than retrying unchanged.
- Do not stack unrelated segments into one list; one TAM definition per list keeps criteria columns meaningful.
- After sourcing, the natural next steps are contacts and enrichment — see the `enrich-contacts` skill — and scoring, see `rank-by-icp`.

## Scope and authorization

An estimate-only request does not authorize creating a list or starting sourcing. Stay within
the requested company count, criteria and authorized budget. Reuse existing authorization
for the same scope; do not repeat paid runs solely to improve an answer.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: enrich-contacts
description: "Research company data, custom buying signals and business contact details in Compelling lists; find decision-makers when needed. Use for technologies, certifications, hiring activity, work emails or LinkedIn profiles, for companies in the user’s chosen markets (Firmenrecherche, Ansprechpartner, Datenanreicherung). Reading saved values alone does not require new research."
---

# Research companies and contacts in Compelling

The single most important rule: **contact discovery and enrichment are separate steps.**
`compelling_find_contacts` returns only name + job title. Emails, phone numbers, LinkedIn
URLs, and every other data point are **insights** — columns you define once and then research.

## Workflow

1. **Confirm the workspace** (`compelling_get_workspace`) and locate the list (`compelling_list_lists`).
2. **Choose the requested work.** For company-only research, skip contact discovery and work
   with `record_type='accounts'`. Read saved values without new research when that is all the
   user asks for. **Find contacts only when requested or necessary to identify the requested
   decision-makers**, using `compelling_find_contacts`:
   - Pass `roles` (title + optional persona + `per_title_limit`) to define who to look for, or omit to use the list's configured roles.
   - Cap spend with `limit` (accounts processed). Costs 2 credits per contact — offer `compelling_estimate_credits(action='find_contacts')` first.
   - It is asynchronous: pass `wait_seconds`, or long-poll `compelling_contacts_run_status`.
3. **Define the enrichment column** with `compelling_add_insight` (free — defining a column researches nothing):
   - Contacts: `email`, `personalLinkedin` (NOT `linkedinUrl` — that is the account-level value), `salutation`, `phoneNumber`, `premiumPhoneNumber`.
   - Accounts: `revenue`, `industry`, `employees`, `linkedinUrl`, `hqPhone`, …
   - Anything else is a custom type (`boolean`, `singleChoice`, `multipleChoice`, `integer`, `entity`, `url`, `date`, `jobtitle`, …) and needs a `question` + `header_name`; for accounts include `{company_name}` and `{domain}` in the question.
   - Custom company questions can cover SAP usage, ISO 13485 certification or current hiring.
     Preserve any time window the user specifies; do not present historical evidence as current.
   - Reuse existing columns — check `compelling_list_insights` before adding duplicates.
4. **Research the values** with `compelling_run_insight`. It requires an **explicit scope**: pass `account_ids`/`contact_ids` or a `limit` — there is no "run on everything" default. Credit-spending; offer an estimate first.
5. **Poll** `compelling_insight_status` (with `wait_seconds`), then **read values** via `compelling_read_list` — ground truth.

## Bringing your own data

If the user already has accounts/contacts (CRM export, CSV), write them directly with
`compelling_ingest_records` — no research, zero credits. Identify accounts by `domain`
(resolve-or-create) or `account_id` (attach existing). Known values go in as final insight
answers via existing `question_id`s.

Ingest can overwrite existing insight answers. Before replacing values, explain the affected
records and columns and obtain authorization for those replacements. Use authorization the
user has already given; do not ask again for the same scope.

## Credit authorization

An estimate-only request does not authorize starting a paid run. If the user asks for a cost
preview or explicitly withholds approval, return the estimate (or ask for missing scope)
without starting contact discovery or enrichment. When the user has already authorized the
paid action and its scope, proceed without asking for the same authorization again.

## Pitfalls

- There is no single "find contacts with email" call — find contacts first, then run the email insight on them.
- `record_type='accounts'` takes `account_ids`; `contacts` takes `contact_ids` — never mix.
- Counters are eventually consisten

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: feedback
description: Report a bug, rough edge, or feature request for Compelling or this plugin. Use when a Compelling tool call fails unexpectedly, returns wrong data, or the user says they want to report a problem or give feedback about Compelling.
---

# Send feedback about Compelling

Route feedback to the right channel and include enough context to make it actionable.

## Gather context first

Before filing anything, collect (from the conversation, not by re-running paid tools):

- What the user tried to do, and which tool call failed or misbehaved (tool name + arguments, minus anything sensitive).
- The exact error text or the unexpected output.
- The `list_id` / `question_id` involved, if any.
- Which AI client the user is working in (for example ChatGPT, Codex, Cursor).

**Never include credentials, tokens, or personal contact data (emails, phone numbers) in a report.**

## Channels

- **Plugin or MCP issues** (tool errors, schema problems, skill gaps): open a GitHub issue at
  https://github.com/seekwhens/compelling-plugin/issues — draft the title and body for the user,
  then let them review before anything is posted.
- **Product issues or account questions** (credits, billing, data quality, workspace access):
  point the user to the in-app support chat at https://app.compelling.ai (bottom-right beacon)
  or the contact options on https://compelling.ai.

## Draft format for GitHub issues

```
Title: <one-line symptom, e.g. "run_insight returns dispatch_failed for contact email columns">

**What I did:** <tool + arguments>
**What happened:** <error/output>
**Expected:** <what should have happened>
**Client:** <the AI client in use>
```

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: rank-by-icp
description: "Prioritize target companies in a Compelling list using an explicit weighted customer-fit rubric and a 0-100 account score. Use for best-fit prospects, lead scoring or deciding which companies to approach first (Zielkunden bewerten, Vertriebsprioritäten). General sales advice or explanations of ICP do not require ranking a list."
---

# Prioritize target accounts in Compelling

Ranking scores every account 0-100 from an **explicit rubric over insight columns** — no
black box. Costs 1 credit per account.

## Workflow

1. **Discover the columns** with `compelling_list_insights(record_type='accounts')` — you need each column's `question_id` and answer type. Rankable columns must exist and be researched first (see `enrich-contacts` / `build-tam-list`).
2. **Build the rubric with the user.** For each column pick exactly ONE points spec, matching its type, points 0-10:
   - `value_points` — for `boolean`, single-choice, and `tamCriteriaMatch` columns: map each value to points (e.g. `{"true": 10, "false": 0}`).
   - `range_points` — for `integer` columns: numeric ranges to points (e.g. 50-200 employees → 10).
   - `choice_points` — for multiple-choice columns: points per selected option.
   Weight what actually predicts fit; 3-5 columns beat ten noisy ones.
3. **Offer a cost preview** with `compelling_estimate_credits(action='rank_list')` (1 credit x accounts in the list).
4. **Start scoring** with `compelling_rank_list(weights=[...])`. Asynchronous — pass `wait_seconds` or long-poll `compelling_ranking_status`.
5. **Explain the criteria and weights**, including which researched company values drive fit.
   Distinguish customer-fit scores from confirmed purchase intent; missing research is unknown.
6. **Read the ranked list**: `compelling_read_list(record_type='accounts', sort_by=<ranking question_id>, sort_dir='desc')` for top-N by fit. The ranking column's `question_id` is returned by `compelling_rank_list` / `compelling_ranking_status`.

## Pitfalls

- Accounts-only: contacts cannot be ranked.
- A column with unresearched values contributes nothing for those accounts — enrich first, rank second.
- Ranking columns themselves cannot be ingested or re-ranked; re-run `compelling_rank_list` with a new rubric to re-score.
- Present the rubric back to the user before starting — the scoring is only as good as the agreed weights.

## DACH examples

Customer criteria may include country, employee count, SAP usage or a researched certification.
Use the user's actual rubric; do not assume that a DACH location or any single signal means a
company is ready to buy. Present results in the user's language.

Referenced files: 1 — file references are metadata, not package contents.