---
name: privsource-target-lists
description: Use when an agent builds, refines, monitors, or enriches PrivSource Target Lists — researched lists of companies matching natural-language filters — through MCP.
---

# PrivSource Target Lists

Target Lists find companies matching filters — sector, size, geography, and anything else the description states. Filters describe the target companies themselves, not their acquirers; use buyer-list tools when the user wants acquirers for a company being sold. Builds run asynchronously and can consume credits.

## Workflow

1. Call `privsource_whoami` if unsure whether the account has `target-lists` access. When both the buyer and seller accounts have access, `create_target_list` requires an `account_type`.
2. Call `list_target_lists` to find existing lists before creating a new one.
3. Call `create_target_list` with a natural-language `description` of the companies to find. `requested_count` defaults to 25 and caps at 1000. Creation can consume credits, so confirm intent first.
4. Poll `get_target_list_current_version` while `status` is `analyzing` or `processing`. Call `get_target_list_results` at any time to read rows as they complete — do not wait for the full build to finish.
5. The build is done when `status` is `ready`, or `ready_with_contacts` once leadership research completes.

## Refining and Growing

- `refine_target_list_filters` creates a new version from an updated description and starts a new asynchronous build.
- `add_target_list_rows` raises the requested row count for the current version; the new total must exceed the current row count.
- `update_target_list` renames or archives/unarchives the list; it never changes filters, rows, or enrichment.
- `cancel_target_list` stops an in-progress build or enrichment run.

## Enrichment

- `update_target_list_data_columns` adds researched company attributes (a title, an optional research instruction, and an expected format) or removes columns by id. Data columns are extra attributes, not contact research.
- `request_target_list_leadership` researches CEO/Owner leadership for the rows; `include_phone: true` adds phone lookups at extra credit cost. Poll `get_target_list_current_version` while `status` is `processing_contacts` until it is `ready_with_contacts`.

## Error Handling

- Creates, refines, row additions, data columns, and leadership can consume credits — if a tool returns a payment, allowance, or credit error, stop and report the exact message.
- Versions are immutable history: `get_target_list` lists them and `get_target_list_version` fetches one; results default to the current version.
- Use ids returned by the tools verbatim. Do not synthesize ids.

## Exports

Call `get_target_list_export` with the list `id` and optional `version_number`.
The response returns the file directly in `export.content`. No browser sign-in is needed.
If `encoding` is `base64`, decode `content` to bytes. If it is `utf-8`, use the text directly.
Save the result using `filename` and `content_type`, or analyze the CSV text in the agent.
Check `ready` first. Unavailable exports return `unavailable_reason` without file content.
The stored file keeps the selected version’s filters and data columns. Missing files remain unavailable.
`dashboard_url` is optional context. It is not required to get the file.