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

# Tools

> The ten MCP tools, what each one takes and what it gives back.

Ten tools, in four groups. `tools/list` shows what your credential allows, not the whole
catalogue.

| Group | Tools | Scope |
| - | - | - |
| [People and companies](#people-and-companies) | 3 | `read` |
| [Content and numbers](#content-and-numbers) | 2 | `read` |
| [Lists and sources](#lists-and-sources) | 2 | `read` |
| [Changing things](#changing-things) | 3 | `write`, `runs` |

> [!NOTE]
>
> Use names, not ids. `search_people` and `update_person` take audience names, and `radar`
> takes a source `display_name`. An unknown name answers with the names that exist.

***

## People and companies

### search\_people

Find people on any combination of profile, fit, warmth, recency and outreach count.

**search** `string`

Free text over name, headline, title, company, location and industry. A pasted profile URL
matches that one person.

**days** `number`

Engaged in the last N days.

**min\_fit** `number`

Fit score floor, 0 to 100.

**max\_outreach\_count** `number`

Ceiling on times approached. `0` means never approached.

**audience** `string`

An audience name, not an id.

**engaged\_with\_post** `string`

A `post_id`. Answers "who engaged with this one post".

**Returns** `total`, a compact row per person and `next_cursor`.

**Use next** `get_person` to open one. `update_person` or `log_outreach` to act.

> [accordion] All parameters
>
> `search`, `country`, `seniority`, `industry`, `stage`, `min_fit`, `max_fit`,
> `min_followers`, `min_connections`, `max_outreach_count`, `days`, `engaged_since`,
> `first_engaged_since`, `audience`, `engaged_with_post`, `comment_contains`, `company_id`,
> `sort`, `limit`, `cursor`.
>
> With `engaged_with_post` each row also carries the `engagement` itself. The other filters
> do not apply to that question.

### get\_person

Everything about one person, right before you write to them.

**person\_id** `string`

The id from a search row.

**name** `string`

A name instead of an id.

**linkedin\_url** `string`

A profile URL instead of an id.

Pass exactly one of these three.

**Returns** the profile with fit and warmth, the timeline of what they did, what you sent
them, and their audiences.

**Use next** `log_outreach` after you send something. `update_person` to change their stage.

> [accordion] All parameters and the candidates answer
>
> Also `activity_limit` and `outreach_limit`.
>
> A name that matches several people answers with `candidates` instead. Pick one and ask
> again with its `id`. That is an answer, not an error.

### search\_companies

Companies where several of your people work, and who works at one of them.

**company\_id** `string`

One company, with the people from your workspace who work there.

**search** `string`

Free text over the company name.

**min\_people** `number`

Only companies with at least this many of your people.

**min\_fit** `number`

Fit score floor, 0 to 100.

**Returns** a compact row per company, or one full company record with its people, best fit
first.

**Use next** `get_person` on one of the people that came back.

> [accordion] All parameters
>
> `company_id`, `search`, `industry`, `country`, `min_fit`, `min_people`, `size_min`,
> `size_max`, `sort`, `limit`, `cursor`.

***

## Content and numbers

### list\_posts

Your own posts with their numbers.

**posted\_since** `string`

A UTC day, `YYYY-MM-DD`.

**search** `string`

Free text in the post body.

**exclude\_reshares** `boolean`

Leave reshares out.

**sort** `string`

How to order the page.

**Returns** your posts with likes, comments, impressions, views and followers gained.

**Use next** `search_people` with `engaged_with_post` set to a `post_id` from one of these
rows.

> [accordion] All parameters
>
> `sort`, `posted_since`, `search`, `exclude_reshares`, `limit`, `cursor`.

### get\_insights

What this period did against the one before it.

**days** `number`

The window. The previous window of the same length is the comparison.

**person\_ids** `string[]`

Narrow to specific team members.

**Returns** reach and qualified counts, trends, the five best and five worst posts by ICP
engagement, and breakdowns of the audience.

**Use next** `search_people` with `days` and `min_fit` to get the people behind the numbers.

> [accordion] Everything in the answer
>
> Breakdowns by format, hook, CTA, media and visual type. Audience by country, seniority,
> follower band, industry and company size. Plus top companies, posting cadence and
> per-team-member results.
>
> No daily series. This is the summary, not the chart data.

***

## Lists and sources

### list\_audiences

The audiences of this workspace, and their names.

**limit** `number`

Page size.

**cursor** `string`

The `next_cursor` from the previous page.

**Returns** the audiences with how many people and companies are in each.

**Use next** `search_people` with `audience` to see who is in one.

> [accordion] What is left out
>
> Archived audiences are not listed. The counts are the state of the last scoring round, not
> of this second.

### radar

List what you track, and add, pause or resume a source.

**action** `string` *required*

`list`, `add`, `pause` or `resume`.

**type** `string`

On `add`: `person`, `company` or `keyword`.

**display\_name** `string`

The name of the source. Also accepted by `pause` and `resume`.

**source\_kind** `string`

`team`, `competitor`, `influencer` or `market`.

**source\_id** `string`

An id instead of a display name, on `pause` and `resume`.

**Returns** `sources` for `list`, or the single `source` that was touched.

**Use next** `search_people` to see who a source brought in. `refresh_data` with
`kind: refresh_source` to fetch new posts for one.

> [accordion] All parameters and the scope rule
>
> `list` takes `status` and `limit`. `add` takes `type` with the matching `person_id`,
> `company_id` or `keyword_query`, plus `display_name`, `source_kind` and an optional
> `label`. `pause` and `resume` take a `source_id` or a `display_name`.
>
> The tool itself is `read`, because listing is reading. The three write actions check their
> own scope and refuse with a readable message on a read-only key.

***

## Changing things

### update\_person

Set stage, notes, tags and audience membership, on up to 200 people at once.

**person\_ids** `string[]` *required*

Always a list, even for one person.

**stage** `string`

`lead`, `customer`, `peer`, `watchlist`, `disqualified`, or `null` to clear.

**notes** `string`

`null` clears the notes.

**tags** `string[]`

Replaces the whole list.

**add\_to\_audiences** `string[]`

Audience names.

**remove\_from\_audiences** `string[]`

Audience names.

**Returns** how many were updated, which ids were unknown, and for a single id the person
as they are now.

**Use next** `log_outreach` if you also actually sent something.

> [accordion] Unknown ids
>
> An unknown id is not an error. The rest is updated and the unknown ids come back in the
> answer.

### log\_outreach

Record that you reached out to someone.

**person\_id** `string` *required*

Who you contacted.

**channel** `string` *required*

`linkedin_message`, `email`, `call` or `other`.

**note** `string`

What you sent.

**occurred\_at** `string`

Defaults to now. Pass it only when backfilling.

**tags** `string[]`

Added to the existing tags, never replacing them.

**Returns** the logged act, the person, and `replayed` when this is the stored answer to an
identical earlier call.

**Use next** `search_people` with `max_outreach_count: 0` to find the next untouched person.

> [!WARNING]
>
> `outreach_count` and `last_outreach_at` on that person are rebuilt nightly and lag one
> night. The act itself shows up immediately in `get_person`.

### refresh\_data

Queue background work, and poll where a run stands.

**kind** `string`

`refresh_source`, `enrich` or `rescore`.

**source\_id** `string`

Required by `refresh_source`.

**audience\_id** `string`

Scopes the work to an audience. Needs `confirm`.

**confirm** `boolean`

Agreement to spend credits on a whole audience.

**webhook\_url** `string`

An https URL called when the run finishes, instead of polling.

**run\_id** `string`

Pass alone to ask where an earlier run stands.

**Returns** the `run`, or `needs_confirmation` with `people_count` and a message.

**Use next** call again with the `run_id` to poll. Wait seconds between polls, not
milliseconds.

> [!WARNING]
>
> This tool spends credits. Work on a whole audience answers `needs_confirmation` first. Call
> again with `confirm: true` only after the user agreed.
>
> Fresh data takes minutes to hours to show up in `search_people`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.