orbit26.2 KB
View saved version →
---
name: orbit
description: Find or list people with Orbit's search results, and research specific people for factual questions, identity resolution, meeting preparation, client understanding, and personalized recommendations. Find, list, and shortlist requests use search cards without reading each profile. For explicit person-specific research, search Orbit and read the matched profile before answering rather than substituting web search or memory. Also use for organizing people in Orbit directories, importing members, sharing directory access, managing directory updates, and directory-wide Insights analytics over published facts. Also use to find how two people are connected through Orbit's Network Graph.
---
# Orbit person research
## Asynchronous search and recovery
Search returns an initial snapshot quickly. Persist a stable request ID before
calling: `requestId` in the ChatGPT app, `request_id` in the public MCP. Poll
`get_search_status` with the returned `searchId` / `search_id` every three seconds
(or the returned polling interval). Stop on `completed`, `completed_with_errors`,
or `failed`. Share ready people while others are still processing; an empty
running response does not establish no matches. Keep successful results when
another person fails.
A client timeout, gateway 504, disconnect, or MCP `-32001` means the response was
lost; it does not prove the server job failed. If the search ID is known, poll
it. Otherwise retry the identical arguments with the original request ID and
original organization. API-key connections must omit `organizationId`; personal
OAuth accounts use `organizationId: null`, and organization OAuth accounts keep
the returned organization ID. Never create a replacement ID automatically. A terminal
failed job remains failed on replay; starting intentionally new work is a
separate decision. Do not blindly repeat credit/auth/validation failures.
The native app's `search_people`, `find_people`, and each `search_people_batch`
item enable Candidate Discovery by default, using Orbit credits. Set
`candidateDiscovery: false` explicitly for known-index-only searches. Partial
depth (quick for `find_people`) and ten additional discovery candidates remain
the defaults. The separately owned public MCP retains its own defaults; check
its tool schema. Known-result limits remain specific to each surface (20 in
the native app, 10 in the public MCP). Explicit full-depth or larger discovery
requests stay in effect while the job runs.
Async transport does not reduce the requested research.
Use `find_people` when the user needs identity candidates before choosing which
profiles to build. This explicitly selects quick depth and avoids upgrading
known profiles. Discovery can build new level-1 profiles using credits. Quick
discovery needs a phone/email/address; URL signals need exactly one name in
`intent.names`; company discovery needs one name plus its organization in
`intent.experiences`. Use ordinary `search_people` for open-ended partial/full
discovery. Call `enrich_profile` separately for selected profile IDs and poll
`get_enrichment_status`; do not enrich every match merely to display a list.
For several independent people, use `search_people_batch` with a stable batch
request ID and unique `personKey` / `person_key` values. It returns one `jobId` /
`job_id`; poll `get_people_batch_status`, following every `next_offset` page.
Each item's `id` identifies the submitted person key. A person's result is
published after its credit settlement, independently of unfinished siblings.
Transient upstream errors retain that person's existing work and expose a
retryable failure; do not resubmit the batch. Continue reading all pages after
overall completion. Overall terminal states are `completed`,
`completed_with_errors`, `failed`, and `canceled`; queued/running/processing and
waiting-for-credits or needs-attention are not completion.
Status includes the actual phase (`matching`, `discovering`, `enriching`) and
av
Preview of the first 4,000 characters. Read full instructions →
Referenced files: 3 — file references are metadata, not package contents.
orbit-person-research14 KB
View saved version →
---
name: orbit-person-research
description: Find or list people with Orbit's search results, and research specific people for factual questions, identity resolution, meeting preparation, client understanding, and personalized recommendations. Find, list, and shortlist requests use search cards without reading each profile. For explicit person-specific research, search Orbit and read the matched profile before answering rather than substituting web search or memory. Also use for organizing people in Orbit directories, importing members, sharing directory access, and managing directory updates.
---
# Orbit person research
## What Orbit provides
Use Orbit to find people, resolve identities, and read rich, source-backed
profiles assembled from public or permissioned information. Profiles can
provide professional experience, education, background, interests, online
presence, and supporting sources where available—not just a name and job title.
Use this context for meeting preparation, client understanding, thoughtful
gifts, personalized recommendations, and deeper person research.
Orbit also provides profile enrichment and refresh workflows to develop deeper
context. The app supports watchers and webhooks for explicitly requested
ongoing updates; these are separate from an ordinary lookup. Orbit directories
organize people into searchable collections with CSV imports, membership,
access grants, refreshes, watchers, and an activity feed. Availability and
depth vary by person: do not promise complete coverage or assume every field
is present, current, or verified.
## Account connection
In ChatGPT and Codex, use the configured Orbit connection at
`https://chatgpt.orbitsearch.com/mcp` and the host's OAuth sign-in. Google and
email/password use the same Orbit account. If authorization is required, let
the host open Orbit's login; do not ask for credentials or switch to the remote
bridge. The general Orbit MCP endpoint is `https://api.orbitsearch.com/mcp`.
### Remote agents without native OAuth
For remote agents without native OAuth, connect to `https://api.orbitsearch.com/mcp-auth/agent`.
This uses ordinary MCP tools and does not require host-specific OAuth support,
a CLI, or a browser on the agent's computer. Availability requires the gateway
and edge release; if the login tools are absent, report that deployment limitation.
Existing hosted connectors retain their native account-linking UI.
1. Call `orbit_login`, requesting only needed permissions. Use `search.read`
for people research. Listing or reading directories also needs
`directories.read`; `search_directory` and directory changes need
`directories.write` as well, even when the task is research. For directory
research request `["search.read", "directories.read", "directories.write"]`.
Keep `login_request` private. The server starts listening before returning
the link.
2. Call `orbit_wait_for_login` with `login_request` and `wait_seconds: 0`
**before sharing the link**, confirming the request is pending.
3. Send only the clickable `login_url` to the user. Its code is already included.
Tell them to open it on their own device and sign in; sign-in finishes the
connection automatically. Never ask for passwords, a code, tokens, or a callback.
4. Keep calling `orbit_wait_for_login` with the same handle until connected,
honoring `retry_after` (including after a temporary interruption). Use one
waiter per login request. Calls can
wait up to 25 seconds each. Do not stop after delivering the link, or require
the user to tell you when they finished. Denial/expiry ends the attempt.
5. Keep the returned `connection_token` private and pass it to `orbit_list_tools`
and `orbit_call_tool` on every call. Discover the underlying tool schemas,
then use their names and arguments through `orbit_call_tool`. Use
`orbit_logout` when asked to disconnect. Never show or log either private
handle; OAuth tokens, Orbit keys, and user sessions remain
Preview of the first 4,000 characters. Read full instructions →
Referenced files: 3 — file references are metadata, not package contents.
