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

# Orbb Research tools

> Every tool on https://mcp.orbb.com/mcp/research: what it does, what it takes, and what it costs.

| Tool | Does | Cost |
| - | - | - |
| [`orbbai_who_knows_them`](#orbbai_who_knows_them) | Who is around one person, and how well they know them | Free, one call |
| [`orbbai_who_knows_someone_there`](#orbbai_who_knows_someone_there) | A way into a company: who left, and who they overlapped with inside | Free, one call |
| [`orbbai_capabilities`](#orbbai_capabilities) | What Orbb can and cannot answer | Free |
| [`orbbai_playbooks`](#orbbai_playbooks) | Worked workflows teams build on this data | Free |
| [`orbbai_held`](#orbbai_held) | What your account has already researched | Free |
| [`orbbai_people_resolve`](#orbbai_people_resolve) | Names in, candidate handles out | Free |
| [`orbbai_plan`](#orbbai_plan) | What a research run would take and cost | Free |
| [`orbbai_run_start`](#orbbai_run_start) | Agree to a plan and start it | **Research Tokens** |
| [`orbbai_run_status`](#orbbai_run_status) | Where a run is, and what it has found | Free |
| [`orbbai_run_stop`](#orbbai_run_stop) | Stop a run and keep what it found | Free |
| [`orbbai_routes_from_research`](#orbbai_routes_from_research) | Ranked routes out of finished research | Free |
| [`orbbai_table_narrow`](#orbbai_table_narrow) | A new table from one already built, by conditions in sentences | A small cost per row |
| [`orbbai_ours_remember`](#orbbai_ours_remember) | Record who is on your own side | Free |

Every tool answers with text for the model to read. Where there is more — a plan id, a run record, candidates — it is also in the result's `structuredContent`. Refusals ("this needs a goal") are ordinary answers, not errors: read them and call again.

## Look around

### `orbbai_who_knows_them`

One person in; the people around them, each with how strong the tie is and the evidence under it — who they worked alongside and for how long, who they interact with publicly, and where each of those people is now. One call: no plan, no approval, nothing to poll.

It pins the person itself. A LinkedIn URL or public id is read directly; a full name is resolved on the open record, and the answer says how sure it was. Where a name really is several people, it lists them instead of guessing.

**person** `string` *required*

A LinkedIn profile URL, the public id after `/in/`, or a full name. **A single word is read as a public id**, never as a name — for somebody known only as "Dana", send the full name.

**company** `string`

Where they work. This is what pins a common name. Ignored when `person` is a URL or public id.

**email** `string`

Their work email. Read only when `company` is not sent.

**about** `string`

What the introduction is for, if the question says — `"revenue"`, `"engineering"`, `"anyone senior"`. Ranks and filters the people around them by what each does now and did then. Without it, the answer is whoever they know best rather than whoever matters here.

**userIs** `string`

**Your own user's** LinkedIn URL. The answer then says which of these people your user has worked alongside themselves — a path that needs no introduction.

**userWorksAt** `string`

Your own user's employer, by name or domain. Marks anybody already reachable from your side.

> [!NOTE]
>
> This reads a few people off the record and cannot rank them against a goal. "Every relationship, scored and ranked" is a [research run](https://docs.orbb.com/mcp/runs.md).

### `orbbai_who_knows_someone_there`

One company in; ways in out. Each is a named person who **left** that company and a named person still **inside** whose time there overlapped theirs, with how many months they were there together. The person who left is the one you can approach.

**company** `string` *required*

A domain (`snowflake.com`), a name, or a LinkedIn id `company/<slug>`. A name is a guess, and the answer says which company it read. A LinkedIn company URL is not read — send the `company/<slug>` id.

**about** `string`

The part of the company that matters — `"engineering"`, `"sales"`, `"security"`.

**inCity** `string`

A city, state or country, when the question names one. Somebody whose record names no place is not excluded: "we do not know where they are" is not "they are somewhere else".

**userIs** `string`

Your own user's LinkedIn URL.

**userWorksAt** `string`

Your own user's employer.

> [!TIP]
>
> For **who is worth talking to** at a company — rather than who can get you in — check `orbbai_held` first, then plan a company run.

## Orient

### `orbbai_capabilities`

What Orbb can and cannot answer. Called bare, a short overview and the questions it settles, with how much of each is public record and how much needs data only you hold.

**about** `enum`

`overview` (the default), `kinds` (the kinds of research, their limits and depths), `asking` (what makes an introduction land), `questions`, or `all` — every part at once, and long.

### `orbbai_playbooks`

A library of worked workflows: scoring accounts by who you can reach, finding the route into every open opportunity, spotting deals with no relationship behind them, prioritising outbound by warm access, finding a missing executive sponsor, picking an event invite list. Each says when it runs, the steps, the calls it makes, and what your own systems must supply — either to run once now with these tools, or as a build spec for your own automation.

**about** `string`

What your user is trying to do, in their words — `"prioritise outbound"`, `"we keep losing deals we have no relationship into"`. Returns the two or three that fit. Omitted, the shortest overview.

**slug** `string`

One playbook, in full, with a worked example.

### `orbbai_held`

What your account has already researched, by kind and date. An answer from research already done is immediate and free; researching the same subject again spends tokens to learn nothing new.

**about** `enum`

Limit to one kind of research: `person`, `people` or `company`. Omitted, everything.

**ask** `string`

What you are looking for, in your user's words.

## Research

### `orbbai_people_resolve`

Turns names into the **handles** `orbbai_plan` takes. Returns candidates and never picks: a common name comes back as several people, each with a headline and company.

**names** `string[]` *required*

1 to 25 names. Each is a full name or a LinkedIn URL. Add a company or title where you have one — `"Dana Mor, Head of Data at Acme"` resolves far more often.

**ask** `string`

What this is for, in your user's words. Later calls in this conversation weigh answers against it.

Each entry in `resolved` has the name `asked` and its `candidates` — `handle`, `name`, `headline`, `company`, and `held` when Orbb already has research on them. `settled` is set when exactly one researchable profile matched.

### `orbbai_plan`

What a research run would take: a price in Research Tokens, a time, and a `planId`. **Nothing starts.** What you give decides the kind of run, and every kind takes the goal in `ask`.

**ask** `string`

What your user wants, in their own words — a sentence, not a filter. Optional in the schema, but most plans are refused without it.

**handles** `string[]`

Up to 40 handles from `orbbai_people_resolve`. Plans a **person** run.

**company** `string`

One company, by name or domain. Plans a **company** run: who inside it is worth going through. Answers with a `run` id for the shortlist rather than a `planId`.

**titles** `string[]`

Up to 20 roles — `["VP Data", "Head of Analytics"]`. With `country` or `cities`, plans a **search** across the whole public index, with a column per condition and a yes, no or not-checked in every cell.

**country** `string`

A country code or name. A search that says nowhere is refused.

**cities** `string[]`

Up to 20 cities.

**companies** `string[]`

Up to 50 domains or names, when a search is about particular companies.

**depth** `enum`

`fast`, `standard` or `deep`. Leave it out unless your user asked; Orbb chooses.

The answer carries `planId` (or `run` for a company), `questions` worth putting to your user, an optional `outside` block, and `refused` when the plan cannot run — with the one thing missing.

### `orbbai_run_start`

Agrees to a plan and starts it. **Spends Research Tokens** against the account the server is signed in as — the plan carries the price. Takes the plan id and nothing else.

**planId** `string` *required*

The `planId` from `orbbai_plan`, made under the same credential.

The structured result carries the run `id`, a link to it in the console, and `reused: true` when a run for the same subject was already working.

### `orbbai_run_status`

Where a run is and what it has found so far. Runs take minutes; poll.

**runId** `string` *required*

The run id from `orbbai_run_start`.

### `orbbai_run_stop`

Stops a run and keeps what it found — the rows stay readable through `orbbai_run_status`. No refund for what was spent. Harmless on a run already finished.

**runId** `string` *required*

The run to stop.

## Use the results

### `orbbai_routes_from_research`

Routes out of research already finished, ranked against your goal, with the reasoning and two warnings about how to read them. It reads only what your account has already researched, and researches nobody: on a subject nothing has been run on, it says so.

**subjects** `string[]` *required*

1 to 20 handles or companies already researched.

**ask** `string` *required*

What your user is trying to achieve. **Required here** — without a goal there is nothing to rank against, so it refuses.

### `orbbai_table_narrow`

A **new** table from one a run already built, keeping the rows that meet conditions written as sentences. The original is untouched. Each row is judged against the conditions, at a small cost per row, so send every condition in one call.

**table** `string` *required*

The table id a run gave you, in the text of its answer.

**keep** `string[]` *required*

1 to 20 conditions, as plain sentences — `"has changed job in the last year"`.

**called** `string`

A name for the new table.

### `orbbai_ours_remember`

Records who is on your own side — colleagues, advisors, investors, customers, former teammates. Every later answer takes them into account, and routes through them rank first. Adds and never removes.

**kind** `string` *required*

Your user's own word for the relationship — `"design partner"`, `"former colleague"`, `"board member"`. The vocabulary is open on purpose.

**people** `object[]` *required*

1 to 100 people.

**person**

**name** `string` *required*

Full name.

**company** `string`

Where they are now.

**linkedin** `string`

Their LinkedIn URL — best for pinning them down.

**note** `string`

Anything that changes how the relationship should be used: who owns it, how warm, when it was last live, what not to ask for.


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