> ## 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.

# Workspace tools

> Every tool on https://mcp.orbb.com/mcp: your organization's own relationship graph.

The workspace server answers from **your organization's own data in Orbb** — the people and accounts in your connected CRM, email, calendar and calls, and who on your team knows them. Every tool is read-only and free. It signs in with OAuth only, and your organization needs MCP access turned on.

| Tool | Does |
| - | - |
| [`orbb_list_personas`](#orbb_list_personas) | The saved personas your search filters can use |
| [`orbb_search_people`](#orbb_search_people) | People by role, engagement, persona, list, CRM state and account |
| [`orbb_search_companies`](#orbb_search_companies) | Accounts by type, opportunities, engagement and graph |
| [`orbb_find_connector_paths`](#orbb_find_connector_paths) | The warmest paths from your team to one account or person |
| [`orbb_find_connector_paths_bulk`](#orbb_find_connector_paths_bulk) | The same, for many targets in one call |
| [`orbb_find_connector_intros`](#orbb_find_connector_intros) | Who one connector can introduce you to |
| [`orbb_get_account_interactions`](#orbb_get_account_interactions) | Recent emails, meetings and calls with one account |
| [`orbb_get_contact_interactions`](#orbb_get_contact_interactions) | Recent emails, meetings and calls with one person |

> [!TIP]
>
> Ids flow between tools: a company from `orbb_search_companies` gives the `accountId` for `orbb_get_account_interactions` and the target for `orbb_find_connector_paths`; a person from `orbb_search_people` gives the `contactId` for `orbb_get_contact_interactions`; `orbb_list_personas` gives the names `personas` takes. Pass `next_cursor` back as `cursor` to page; a search cursor lasts 30 minutes.

## `orbb_list_personas`

List the user's saved persona profiles for this organization. Returns each persona's id, name, departments, seniorities, titles, and excluded titles. Use the returned name (preferred) or id as the `personas` filter on orbb\_search\_people.

> [accordion] The full description your agent reads
>
> ```text theme={null}
> List the user's saved persona profiles for this organization. Returns each persona's id, name, departments, seniorities, titles, and excluded titles. Use the returned name (preferred) or id as the `personas` filter on orbb_search_people.
> ```

Takes no arguments.

**Returns** `{ personas: [{ id, name, departments: Department[], seniorities: Seniority[], titles: string[], excludeTitles: string[] }] }`.

## `orbb_search_people`

Search people across identity, role, engagement, persona, lists, CRM/opportunity, account context, and (opt-in) graph predicates. Filters compose via AND, so fewer filters means broader results.

> [accordion] The full description your agent reads
>
> ```text theme={null}
> Search people across identity, role, engagement, persona, lists, CRM/opportunity, account context, and (opt-in) graph predicates. Filters compose via AND, so fewer filters means broader results.
>
> Filter selection — START broad, NARROW only as needed:
> - `personas` + `account_type` + engagement filters cover most queries. Try these first.
> - Engagement: default to `last_interaction_*` for general "engaged" / "in touch" / "gone quiet" language. Switch to the channel-specific `last_meeting_*` or `last_email_*` ONLY when the user is explicit about meetings ("met with", "face-to-face") or email ("emailed", "email thread"). The `min/max_total_*` filters are lifetime counts, not time-bounded — pair one with a `last_*_after` to approximate "met/emailed N times in the last <window>" (e.g. "people we've met this year" → `last_meeting_after`, NOT `min_total_meetings` + `last_interaction_after`).
> - Job changes: `job_change` (moved company), `role_change` (new title, same company) and `between_jobs` say WHICH kind of change. `job_change_after`/`_before` bound WHEN the person started their current company (month precision) and imply `job_change: true` — so "who changed jobs recently" is `job_change_after`. There is no date filter for a title change or for going between jobs; the booleans alone are not time-bounded.
> - Location filters (`city`, `country_code`, `state`) are ONLY for queries that EXPLICITLY mention a place. DO NOT apply location for queries like "CEOs in pipeline", "champions to re-engage", or "customers in restaurants" — those have no geographic intent.
> - `graph` is expensive (traverses the relationship graph) — apply only after cheaper filters have narrowed the candidate set.
>
> For "who has the best relationship with X" / "who knows X" / "who's closest to X" questions, pass `name: "X"` with `response_format: "detailed"` and read the `connectors` array (already sorted by score desc) or the `top_connector` shortcut — its first/top entry is the colleague with the strongest direct signal to X. This is relationship discovery, NOT intro-shopping — do NOT reach for orbb_find_connector_paths / orbb_find_connector_intros for these.
>
> `name` matches from the start of the name or of any word within it — "corey smith" finds "Corey Smith" and "Ada Corey Smith" but not "jacorey smith". A suffix difference still matches, so verify the returned name before acting on it.
>
> Use orbb_list_personas to discover persona names before passing them here.
>
> Returns `concise` rows by default; pass `response_format: "detailed"` for engagement counts, opportunities, persona matches, raw IDs, relationship `connectors` (+ `top_connector`, the highest-scored colleague/intro path to this person), and `verified_profile` (false → profile not enriched; role/seniority/department may be missing or stale — treat as low-confidence). Paginate with `cursor` (pass `next_cursor` from a prior response; all other args are ignored except optional `limit`).
> ```

| Argument | Type | Required | Description | |
| - | - | - | - | - |
| `name` | string | | Case-insensitive substring across first/last/full name. | |
| `emails` | string\[] (1–50) | | Exact email addresses (case-insensitive). Matches any address ever associated with the contact, including past addresses. Malformed entries are skipped with a warning. | |
| `company` | string | | Current company name OR domain substring. | |
| `role` | string | | Case-insensitive substring on the contact's role. | |
| `seniority` | array of enum: `Entry`, `Mid`, `Senior`, `Senior Leadership`, `Executive`, `C-Level` | | Seniority level(s). Multiple values OR-combined (a contact matching ANY level passes). Use multiple values to be permissive. | |
| `department` | array of enum: `Data Science & Analytics`, `R&D`, `Product Management`, `Sales`, `Marketing`, `Operations`, `Customer Support`, `Customer Success`, `HR`, `Finance`, `Legal`, `Strategy`, `Management`, `IT`, `Procurement & Purchasing`, `Revenue`, `Administration`, `Business Development`, `Other` | | Department(s) the contact works in. Multiple values OR-combined. | |
| `city` | string | | City filter. ONLY apply when the user EXPLICITLY mentions a city. Do not infer geography from context. Anchors a radius (default 50mi) on the contact location. | |
| `country_code` | string | | Two-letter country code. ONLY apply when the user EXPLICITLY mentions a country. Independent filter — does NOT need to pair with `city`. Most queries should not set this. | |
| `state` | string | | State/region filter. ONLY apply when the user EXPLICITLY mentions a state. Most queries should not set this. | |
| `city_radius_miles` | integer > 0 | | Default: `50`. | |
| `last_interaction_after` | string (ISO datetime) | | Latest contact of any kind, email OR meeting. Use for general engagement language ('engaged recently', 'in touch this quarter'). When the user explicitly says 'met' or 'emailed', use last\_meeting\_\* or last\_email\_\* instead. | |
| `last_interaction_before` | string (ISO datetime) | | Latest contact of any kind, email OR meeting, before this time. Use for general dormancy language ('haven't touched in months'). For explicit 'met'/'emailed', use last\_meeting\_\* or last\_email\_\* instead. | |
| `last_meeting_after` | string (ISO datetime) | | Most recent calendar meeting, after this time. Use ONLY when the user is explicit about meetings ('met with', 'face-to-face', 'in-person'). For general engagement, use last\_interaction\_\*. | |
| `last_meeting_before` | string (ISO datetime) | | Most recent calendar meeting, before this time. Use ONLY when the user is explicit about meetings ('haven't met since'). For general engagement, use last\_interaction\_\*. | |
| `last_email_after` | string (ISO datetime) | | Most recent email exchange, after this time. Use ONLY when the user is explicit about email ('emailed', 'email thread'). For general engagement, use last\_interaction\_\*. | |
| `last_email_before` | string (ISO datetime) | | Most recent email exchange, before this time. Use ONLY when the user is explicit about email ('no emails since'). For general engagement, use last\_interaction\_\*. | |
| `min_total_meetings` | integer ≥ 0 | | Minimum number of meetings ever held. Lifetime count, not time-bounded. Combine with last\_meeting\_after for a windowed approximation. | |
| `max_total_meetings` | integer ≥ 0 | | Maximum number of meetings ever held. Lifetime count, not time-bounded. Combine with last\_meeting\_after for a windowed approximation. | |
| `min_total_emails` | integer ≥ 0 | | Minimum number of emails ever exchanged (sent + received). Lifetime count, not time-bounded. Combine with last\_email\_after for a windowed approximation. | |
| `max_total_emails` | integer ≥ 0 | | Maximum number of emails ever exchanged (sent + received). Lifetime count, not time-bounded. Combine with last\_email\_after for a windowed approximation. | |
| `job_change` | boolean | | True = this person has changed company since Orbb first saw them. Not time-bounded on its own — pair with job\_change\_after for "changed jobs recently". Useful for prospecting people who joined a target account or left a customer. | |
| `role_change` | boolean | | True = this person changed title/role at the same company. Not time-bounded, and no date filter applies to it — job\_change\_after/before describe the company move, not the title change. | |
| `between_jobs` | boolean | | True = this person is currently between jobs. | |
| `job_change_after` | string (ISO datetime) | | Only people who changed company AND started the new one on or after this time. Month precision — the underlying value is the LinkedIn start month of the current company, so the day is not meaningful. Implies job\_change: true; it is not a general "something changed" date. | |
| `job_change_before` | string (ISO datetime) | | Only people who changed company AND started the new one on or before this time. Month precision; implies job\_change: true. | |
| `personas` | array of `{ persona_id: string }` \\ | `{ custom: { departments, seniorities, titles?, excludeTitles? } }` | | Persona name/id, or \{ custom: \{ departments, seniorities, titles?, excludeTitles? } }. Use orbb\_list\_personas to discover saved persona names. |
| `personas[].persona_id` | string | | Opaque id of a saved persona, as returned by orbb\_list\_personas. | |
| `personas[].custom` | object | | Inline persona criteria — used instead of a saved persona id | |
| `personas[].custom.departments` | array (min 1) of Department enum | yes | Department(s) the persona belongs to | |
| `personas[].custom.seniorities` | array (min 1) of Seniority enum | yes | Seniority level(s) the persona covers | |
| `personas[].custom.titles` | string\[] | | Optional title substrings to match (case-insensitive) | |
| `personas[].custom.excludeTitles` | string\[] | | Optional title substrings to exclude (case-insensitive) | |
| `list_names` | string\[] | | CustomList names; resolved against the current MCP caller. Unresolved names emit a warning. | |
| `in_crm` | boolean | | Restrict to contacts whose email matches (true) or does not match (false) any contact in your organization's CRM. in\_crm=false loads the full CRM email list before filtering and emits a latency warning. | |
| `has_open_opportunity` | boolean | | True = contacts at accounts with an open opportunity. Useful for "in pipeline" / "active deal" queries. | |
| `closed_won_opportunity` | boolean | | True = contacts at accounts where an opportunity closed-won. Use to find people inside active customer accounts. | |
| `closed_lost_opportunity` | boolean | | True = contacts at accounts where an opportunity closed-lost. Useful for re-engagement and second-attempt outreach. | |
| `opportunity_owner` | string\[] | | Emails or names; resolved to CRM owner records. | |
| `opportunity_stage` | string\[] | | Filter to contacts at accounts with an opportunity in these stages (CRM-specific values). Multiple values OR-combined. | |
| `opportunity_amount_min` | number | | | |
| `opportunity_amount_max` | number | | | |
| `opportunity_closed_between` | array of exactly 2 ISO datetimes | | | |
| `account_type` | array of `customer`, `churned`, `prospect`, `partner`, `other` | | Filter to contacts at accounts of the given type(s). "customer" = active customer; "prospect" = open opportunity exists; "churned" = previous customer; "partner" = partner relationship. Multiple values OR-combined. | |
| `account_type_not` | array of `customer`, `churned`, `prospect`, `partner`, `other` | | Exclude contacts at accounts of these types. Useful to find non-customer warm contacts (e.g. exclude "customer" to find prospects only). | |
| `previous_account_type` | array of `customer`, `churned` | | Filter to people who PREVIOUSLY worked at a customer/churned customer account (and are now elsewhere) — useful for tracking champion job changes and warm leads at new employers. | |
| `account_owner` | string\[] | | Filter to contacts at accounts owned by these account-owner emails or names. | |
| `graph` | object `{ has_path_to_account?: boolean, target_account_name?: string, connector_of?: string[] (max 10) }` | | Expensive graph predicates — narrow with cheaper filters first. Traverses the relationship graph. | |
| `response_format` | enum `concise` \\ | `detailed` | | concise returns compact rows and omits avatar/company-image URLs; detailed adds engagement, opportunities, ids and images. Default: `concise`. |
| `cursor` | string | | Opaque pagination token returned as next\_cursor on the prior call. When set, all other args (except limit) are ignored. | |
| `limit` | integer 1–500 | | Default: `50`. | |

**Returns** `{ items: [...], count: number, has_more: boolean, total?: number, next_cursor?: string, warnings?: string[] }`. Each item: `id`, `link`, `name`, `title?`, `company?`, `city?`, `why?`, `seniority?`, `department?`, `email?`, `verified_profile?`, `last_interaction_at?`, `last_meeting_at?`, `meetings_total?`, `emails_total?`, `persona_matches?`, `lists?`, `in_crm?`, `open_opportunities?: [{ name?, stage?, amount_usd?, owner?: { name?, email? } }]`, `connectors?: [{ type: "colleague"|"best_path", name, email?, score, company? }]`, `top_connector?` (same shape), `raw_ids?: { contact_id, person_id }`. Text content header: `"Found N person(s):"`; empty: `"No people matched the filter."`.

## `orbb_search_companies`

Search companies / accounts as the unit (not individual people) across identity, account\_type, opportunities, engagement aggregates, and (opt-in) graph predicates. Filters compose via AND — fewer filters means broader results.

> [accordion] The full description your agent reads
>
> ```text theme={null}
> Search companies / accounts as the unit (not individual people) across identity, account_type, opportunities, engagement aggregates, and (opt-in) graph predicates. Filters compose via AND — fewer filters means broader results.
>
> When to use: queries about COMPANIES (e.g. "customer accounts in pipeline", "churned customers", "prospects in restaurants industry"). Use orbb_search_people instead when the user asks about INDIVIDUALS ("CEOs in pipeline", "champions to re-engage").
>
> Filter selection — START broad, NARROW only as needed:
> - Identity: `name` / `domain` — resolve a specific account. Prefer `domain` when known (more precise).
> - Segmentation: `account_type` + `industry` + `size_min` / `size_max` cover most "what kind of company" questions.
> - Pipeline: `has_open_opportunity` for general "in pipeline" queries; narrow with `opportunity_stage`, `opportunity_amount_min` / `opportunity_amount_max` (e.g. "biggest open deals"), and `opportunity_owner` (whose deals) when the user is specific.
> - Ownership: `account_owner` for "accounts X owns" / "X's book of business".
> - Engagement: account-level aggregates only — `last_interaction_after` (last touch, any channel) and `min_total_meetings`. Channel-specific meeting/email filters live on orbb_search_people, not here.
> - `graph` is expensive (traverses the relationship graph) — apply only after cheaper filters have narrowed the candidate set.
>
> Same `concise`/`detailed` response format and `cursor` pagination as orbb_search_people.
> ```

| Argument | Type | Required | Description | |
| - | - | - | - | - |
| `name` | string | | Case-insensitive company name — matches from the start of the name or on whole words within it (e.g. "cruises" matches "Princess Cruises"). Prefer domain when known. | |
| `domain` | string | | Single domain. Matches any of the account's known domains. | |
| `industry` | string\[] | | Exact match against the account's industry (e.g. "Restaurants"). | |
| `size_min` | integer ≥ 0 | | Min employee count — mapped to overlapping CompanySizeRangeType buckets. | |
| `size_max` | integer ≥ 0 | | | |
| `account_type` | array of `customer`, `churned`, `prospect`, `partner`, `other` | | Filter accounts by type. "customer" = active customer; "prospect" = open opportunity exists; "churned" = previous customer; "partner" = partner relationship. Multiple values OR-combined. | |
| `account_owner` | string\[] | | Emails or names; resolved to CRM owner records. | |
| `has_open_opportunity` | boolean | | True = accounts with an open opportunity. Useful for "in pipeline" queries. | |
| `opportunity_stage` | string\[] | | Filter to accounts with an opportunity in these stages. Multiple values OR-combined. | |
| `opportunity_owner` | string\[] | | Filter to accounts whose opportunities are owned by these owners (emails or names). | |
| `opportunity_amount_min` | number | | | |
| `opportunity_amount_max` | number | | | |
| `last_interaction_after` | string (ISO datetime) | | | |
| `min_total_meetings` | integer ≥ 0 | | | |
| `graph` | object | | Expensive graph predicates — narrow with cheaper filters first. | |
| `graph.has_path` | boolean | | True = only accounts someone at your org has a known path into, regardless of path strength. | |
| `graph.tier` | array of `1` \\ | `2` | | |
| `graph.has_first_degree` | boolean | | | |
| `graph.has_second_degree` | boolean | | | |
| `response_format` | enum `concise` \\ | `detailed` | | concise returns compact rows and omits avatar/company-image URLs; detailed adds engagement, opportunities, ids and images. Default: `concise`. |
| `cursor` | string | | Opaque pagination token returned as next\_cursor on the prior call. When set, all other args (except limit) are ignored. | |
| `limit` | integer 1–500 | | Default: `50`. | |

**Returns** `{ items: [...], count, has_more, next_cursor?, warnings? }`. Each item: `id` (the `accountId` for `orbb_get_account_interactions`), `link`, `name`, `industry?`, `size?`, `account_type?`, `why?`, `domains?`, `account_owner?: { name?, email? }` (detailed only; `"Unassigned"` = in CRM with no owner), `tier?: 1|2`, `open_opportunities?`, `closed_opportunities?`, `last_interaction_at?`, `meetings_total?`, `top_contacts?: [{ name, title?, score }]`, `raw_ids?: { account_id, crm_account_id? }`.

## `orbb_find_connector_paths`

Find the warmest connector paths (also called "introducers" or "warm intro paths") through the relationship graph to a SINGLE target — either an account (`target: { account_name }`) or a specific person (`target: { person_ref }` with email or name). Prefer an email for `person_ref` and a domain for `account_name` whenever you have one — both resolve unambiguously, while names can match several records and come back as a disambiguation error.

> [accordion] The full description your agent reads
>
> ```text theme={null}
> Find the warmest connector paths (also called "introducers" or "warm intro paths") through the relationship graph to a SINGLE target — either an account (`target: { account_name }`) or a specific person (`target: { person_ref }` with email or name). Prefer an email for `person_ref` and a domain for `account_name` whenever you have one — both resolve unambiguously, while names can match several records and come back as a disambiguation error.
>
> When to use: after identifying ONE specific company or person via orbb_search_companies / orbb_search_people, call this to discover who internally can make the introduction.
>
> DO NOT use for exploratory listing of warm intros — use orbb_search_people with `graph.has_path_to_account` to find candidates first. DO NOT call in a loop across many targets — this is single-target.
>
> DO NOT use for "who has the best relationship with X" / "who knows X" / "who's closest to X" — those are relationship-discovery questions (which colleague already has the strongest direct signal to X), not intro-shopping. For those, call orbb_search_people with `name: "X"` and `response_format: "detailed"` and read the `top_connector` / `connectors` fields.
>
> Returns up to `max_paths` paths (default 3, max 10), ranked by `composite_score` — the canonical value, which folds the path score together with how close the connector is to your organization. Higher is better; it has no fixed ceiling, so compare paths against each other rather than against an absolute bar. `score` (0-1) and `connector_closeness_to_org` are its inputs; `connectors[].score` is an absolute closeness figure and is absent when closeness was not measured. Sort on `composite_score`.
> `strength` labels the path, and `strength_basis` says what it was derived from: `composite` means the label reflects `composite_score`; `path_score_only` means the connector's closeness to your organization was never measured, so the label reflects `score` alone and is not comparable to a `composite` one. A `path_score_only` path is not a weak path — it is an unmeasured one.
>
> `hops` is usually [your colleague, connector, target], but NOT always — a 2-hop path with no colleague at the origin is valid output, so do not assume `hops[0]` is someone at your organization. Check `connectors` before telling a rep who to approach.
>
> Errors with disambiguation candidates when a person name matches multiple people, or when an account name matches multiple companies. Each candidate prints all of its domains AND its `account_id` — re-call with `target: { account_id: "..." }` to pick one exactly. Two accounts can share a domain, so passing a domain is not always enough.
> ```

| Argument | Type | Required | Description | | |
| - | - | - | - | - | - |
| `target` | one of `{ account_name: string }` \\ | `{ account_id: string }` \\ | `{ person_ref: string }` | yes | Resolve the connector chain to an account (by name, domain, or exact id) or to a specific person. |
| `target.account_name` | string | | Company name or domain (e.g. "acme" or "acme.com"). Matched against your organization's book of business first (tolerant name matching; a domain matches exactly), then known companies. | | |
| `target.account_id` | string | | Exact account id, as printed in an ambiguity error or returned by orbb\_search\_companies. Use this when a name or domain matches more than one company. | | |
| `target.person_ref` | string | | Email OR name. Errors on ambiguity. | | |
| `max_paths` | integer 1–10 | | Default: `3`. | | |
| `response_format` | enum `concise` \\ | `detailed` | | concise returns compact rows and omits avatar/company-image URLs; detailed adds engagement, opportunities, ids and images. Default: `concise`. | |

**Returns** `{ target: { type: "account"|"person", name, id, link, image? }, paths: [ pathHop & { connectors?: (contactRef & { score? })[], target_contact?: contactRef } ] }`. Each path/intro object: `hops: string[]`, `score: number`, `strength: string`, `line_labels: string[]`, `connector_closeness_to_org?: number`, `composite_score: number`, `tier: 1|2|null`, `strength_basis: "composite" | "path_score_only"`, `reasoning?: string[]`, `raw_ids: Record<string,string>|null`. Contact refs (`contactRefShape`): `name`, `link?`, `email?`, `role?`, `avatar?`, `companyImage?`, `company?`, `seniority?: string|null`, `persona_matches?: string[]|null`, `segment: string|null` (avatar/companyImage omitted in `concise`).

## `orbb_find_connector_paths_bulk`

Find warm-introduction paths for MANY targets in one call. Use this instead of calling orbb\_find\_connector\_paths in a loop — that tool is single-target and says so.

> [accordion] The full description your agent reads
>
> ```text theme={null}
> Find warm-introduction paths for MANY targets in one call. Use this instead of calling orbb_find_connector_paths in a loop — that tool is single-target and says so.
>
> Each target takes the same shape as orbb_find_connector_paths: an account by name or domain, an account by exact `account_id`, or a person by `person_ref`. Up to 25 per call.
>
> Targets are resolved INDEPENDENTLY. An ambiguous or unknown target reports its own `problem` — including the same disambiguation candidates and `account_id`s a single-target call would give — and the other targets still return their paths. Read `resolved` / `unresolved` for the accounting.
>
> Behaviour, scoring and payload are identical to orbb_find_connector_paths, because this is a wrapper over it: paths are ranked by `composite_score`, `concise` omits image URLs, and `hops[0]` is not guaranteed to be one of your colleagues.
>
> For a single target, prefer orbb_find_connector_paths — the reply is smaller and easier to read.
> ```

| Argument | Type | Required | Description | |
| - | - | - | - | - |
| `targets` | array (1–25) of the same `target` union as `orbb_find_connector_paths` | yes | Up to 25 targets. Each is resolved independently: one ambiguous or unknown target does not fail the others. | |
| `max_paths_per_target` | integer 1–10 | | Default: `3`. | |
| `response_format` | enum `concise` \\ | `detailed` | | concise returns compact rows and omits avatar/company-image URLs; detailed adds engagement, opportunities, ids and images. Default: `concise`. |

**Returns** `{ targets: [{ target: Record<string,string> (echoed), paths?: <same path shape as single>, problem?: string }], resolved: number, unresolved: number }`.

## `orbb_find_connector_intros`

Find who a SINGLE connector can introduce you to (the warm intros that person can make). Answers "who can X introduce me to?".

> [accordion] The full description your agent reads
>
> ```text theme={null}
> Find who a SINGLE connector can introduce you to (the warm intros that person can make). Answers "who can X introduce me to?".
>
> Provide the connector via `connector_ref` (email or name).
>
> When to use: when you have ONE specific person and want the strongest people they can warmly connect you with. This is the INVERSE of orbb_find_connector_paths (which finds connectors who can reach a target you already picked).
>
> DO NOT call in a loop across many connectors — this is single-connector. Returns up to `max_intros` intros (default 10, max 25), ranked by the target's seniority (most senior first), then by how warm the path is. Errors with disambiguation candidates when a name matches multiple people.
>
> DO NOT use for "who has the best relationship with X" / "who knows X" / "who's closest to X" — those are relationship-discovery questions, not intro-shopping. For those, call orbb_search_people with `name: "X"` and `response_format: "detailed"` and read the `top_connector` / `connectors` fields.
> ```

| Argument | Type | Required | Description | |
| - | - | - | - | - |
| `connector_ref` | string | yes | Email OR name of the connector. Errors on ambiguity. | |
| `max_intros` | integer 1–25 | | Default: `10`. | |
| `response_format` | enum `concise` \\ | `detailed` | | concise returns compact rows and omits avatar/company-image URLs; detailed adds engagement, opportunities, ids and images. Default: `concise`. |

**Returns** `{ connector: contactRef & { id }, intros: [ pathHop & { target_contact?: contactRef } ] }`. `line_labels` holds exactly one strength label (single connector→target segment).

## `orbb_get_account_interactions`

Recent two-way communication interactions (emails, calendar events, calls) for ONE account, identified by `accountId`.

> [accordion] The full description your agent reads
>
> ```text theme={null}
> Recent two-way communication interactions (emails, calendar events, calls) for ONE account, identified by `accountId`.
>
> When to use: drill-down companion to orbb_search_companies — after a cheap filter narrows to a few accounts, call this on each to inspect the engagement signal in detail.
>
> DO NOT use for broad listing — limit one account per call. The `accountId` must come from a prior tool call.
> ```

| Argument | Type | Required | Description |
| - | - | - | - |
| `accountId` | string (ObjectId) | yes | ObjectId of the account, as returned by `orbb_search_companies` (the `id` field on each result row). |
| `limit` | integer 1–100 | | Maximum number of recent interactions to return (most recent first). Default: `20`. |

**Returns** `{ accountId, link, name, interactions: [{ timestamp?, interactionType: "MSG_SENT"|"MSG_RECEIVED"|"EVENT_ATTENDED"|"CALL", subject? }], page?: { limit, returned, truncated } }`.

## `orbb_get_contact_interactions`

Recent two-way communication interactions (emails, calendar events, calls) for ONE person, identified by `contactId`. Covers every email address known for this person, so the history can include interactions from their earlier roles.

> [accordion] The full description your agent reads
>
> ```text theme={null}
> Recent two-way communication interactions (emails, calendar events, calls) for ONE person, identified by `contactId`. Covers every email address known for this person, so the history can include interactions from their earlier roles.
>
> When to use: drill-down companion to orbb_search_people — after narrowing to a few people, call this on each to inspect the relationship history in detail.
>
> DO NOT use for broad listing — one person per call. The `contactId` must come from a prior tool call.
> ```

| Argument | Type | Required | Description | | |
| - | - | - | - | - | - |
| `contactId` | string (ObjectId) | yes | ObjectId of the person, as returned by `orbb_search_people` (the `id` field on each result row). | | |
| `limit` | integer 1–100 | | Maximum number of recent interactions to return (most recent first). Default: `20`. | | |
| `interaction_kinds` | array (min 1) of `messages` \\ | `events` \\ | `calls` | | Optional filter by kind: messages (emails), events (meetings), or calls. Omit to include everything. Default: — (all). |

**Returns** `{ contactId, link, name, interactions: [...], page? }` — same interaction shape as the account tool.


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