One MCP server for people/company discovery, enrichment, identity resolution, and contact finding across many providers.
Search for people by role, company, location, keywords, or source URLs (people_search).
Enrich known people with title/employer/location/profiles (people_enrich).
Search and enrich companies by name, domain, industry, or technology (companies_search, companies_enrich).
Read social profiles across LinkedIn, X, GitHub, etc. (social_profile).
Resolve one person's identities across platforms from any handle, URL, or email (people_identity_resolve).
Find or verify contact details like work email and phone (people_contact_find).
Discover image sources and associated profiles from a photo URL (people_from_image).
Inspect capabilities and configured providers (capabilities).
Find and call provider-specific endpoints from a large catalog when unified tools are insufficient (find_tool, endpoint, call_tool).
Run as a self-hosted MCP server over stdio or HTTP/Docker with your own provider API keys.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@openpeoplerouter find contact info for the CTO of Acme Corp"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
One MCP interface for people discovery. Bring your own provider accounts.
Find candidates, researchers, creators, industry experts and business contacts; enrich profiles and companies; resolve identities and discover contact details. Use unified capability tools first, then search the provider endpoint catalog when you need a platform-specific API.
This is an independent, self-hosted project. It has no DINQ login requirement, customer database, credit wallet, markup, payment gateway or hosted deployment dependency. You supply provider API keys and pay the providers directly. DINQ is an optional hosted provider, like a separate paid account you can choose.
中文说明 · Provider configuration · Architecture
Requires Python 3.11+ and uv. From your checkout:
uv sync
cp .env.example .env
# Edit .env locally: add only the provider keys you want to use.
uv run openpeoplerouter providers
uv run openpeoplerouter check
uv run openpeoplerouter serveThe default transport is MCP stdio. It waits for an MCP client and is not an
interactive chat prompt. Environment variables override .env values.
For an MCP client supporting command-based servers, use this configuration with
the absolute path to your checkout and your installed uv executable:
{
"mcpServers": {
"openpeoplerouter": {
"command": "uv",
"args": ["--directory", "/absolute/path/openpeoplerouter", "run", "openpeoplerouter", "serve"]
}
}
}This is a generic MCP configuration example; individual clients can use different configuration formats. No provider key needs to be pasted into a conversation.
Related MCP server: fetchcraft-mcp
Tool | Purpose |
| Find people by criteria or source URL |
| Enrich a known person's profile |
| Find companies |
| Enrich a company's profile |
| Read social account profiles |
| Resolve identities across platforms |
| Discover image sources |
| Find or verify contact details |
| Inspect coverage and available providers |
| Discover endpoints when unified capabilities are insufficient |
| Inspect arguments and provider documentation |
| Execute a provider endpoint with your own credentials |
The initial catalog contains 29 direct HTTP providers and 1,641 endpoint
definitions. Definitions do not mean every API is enabled, tested, free or
available on your plan. Unified routing needs both a configured provider and a
matching adapter. Some capabilities require DINQ or another custom provider
adapter. Use capabilities and find_tool to inspect availability.
# Optional allowlist: only these providers may be called.
OPENPEOPLEROUTER_PROVIDERS=hunter,tikhub,openalex
HUNTER_API_KEY=your-own-key
TIKHUB_API_KEY=your-own-keySet vendor on a unified call to select one provider or endpoint. Set
waterfall=false to try only the first eligible endpoint. The default can call
multiple providers on misses/errors; merging capabilities can call multiple
providers even after a hit. Provider charges may apply to each request.
There is no central credit budget or automatic invoice reconciliation.
Catalog pricing is informational, may be outdated and may differ from your plan.
DINQ_API_KEY=your-own-dinq-key
# Include dinq if you use an allowlist:
OPENPEOPLEROUTER_PROVIDERS=dinq,hunterSelect vendor="dinq" in a unified tool call. This sends the request to the
public hosted PeopleRouter MCP at https://router.dinq.me/test using your DINQ
API key. DINQ's own plan and charges apply. It is never selected automatically,
and other providers work without a DINQ account. The bridge has protocol tests;
no paid DINQ request is made during installation or CI.
# In .env, set OPENPEOPLEROUTER_TOKEN to a long random secret first.
uv run openpeoplerouter serve --transport http --host 0.0.0.0
# Or:
docker compose up --build -dMCP endpoint: http://127.0.0.1:8093/mcp. Supply
Authorization: Bearer <OPENPEOPLEROUTER_TOKEN> when enabled. Docker publishes
only to localhost by default. Use your own TLS reverse proxy for remote access.
This is a single-owner instance: clients share the configured provider keys.
It does not implement per-user accounts or OAuth. Public binding requires a token.
uv run pytest -q
uv buildTests use synthetic responses and in-process MCP clients. They do not spend provider credits. The catalog ships inside the Python package, so installation has no dependency on a sibling repository or the original private project.
To add a provider, see the provider guide.
OpenMailConnect — a standalone, self-hosted MCP server for Gmail and SMTP, maintained by DINQ Labs under Apache-2.0. It provides Gmail search, reading, threads, drafts and sending, plus SMTP sending. Use OpenPeopleRouter to discover people and OpenMailConnect to work with your own mailbox; both can be configured independently in the same MCP client.
OpenMailConnect is optional and is not bundled with OpenPeopleRouter. Follow its installation guide to set up your own Gmail OAuth application or SMTP credentials. It requires no DINQ account or PeopleRouter credits. Sending email requires the user's authorization.
Apache-2.0. See LICENSE and NOTICE. Catalog portions originate from the Apache-2.0-licensed treg project; attribution is retained. Provider services, datasets and subscriptions are governed by their own terms, not by this software license.
Execute a discovered endpoint using your provider key. Provider charges may apply.
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | ||
| endpoint_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral disclosure burden. It does usefully disclose that provider charges may apply and that the provider key is used for authentication, but it does not address potential side effects, failure modes, or rate limits. This is adequate but not comprehensive for a tool that executes arbitrary endpoints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. The core action is front-loaded, and the cost warning is relevant and earns its place. The structure is appropriately tight given the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and a low-detail schema description, the description leaves key context missing: how endpoint_id relates to the discovery flow, what 'args' should contain, and when this tool is appropriate relative to siblings. An output schema exists, so return values are somewhat covered, but the invocation context is under-specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description needed to compensate. It does not explain that 'endpoint_id' identifies a previously discovered endpoint or that 'args' contains the endpoint-specific arguments. The parameter names are somewhat self-evident, but the description adds almost no semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Execute'), a clear resource ('discovered endpoint'), and mentions the provider key. It is distinguishable from the sibling tools like find_tool and endpoint, though it does not explicitly contrast itself with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, and no mention of prerequisites such as first using the 'endpoint' or 'find_tool' sibling to discover an endpoint. The phrase 'discovered endpoint' implies a prerequisite but does not state it explicitly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List unified capabilities, inputs and configured providers. No provider request.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral disclosure burden. It clearly states 'No provider request,' which is a meaningful trait indicating no external side effects. It does not mention read-only status explicitly, but 'List' and the negative statement provide good transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the verb and object, followed by a useful negative clarification. Every word earns its place; there is no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (zero parameters, output schema present), the description is complete. It covers purpose, scope, and a key behavioral trait, so an agent has enough information to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema coverage is 100%, so there is nothing for the description to add about parameter semantics. The baseline for zero-parameter tools is 4, and no additional detail is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and names the resources ('unified capabilities, inputs and configured providers'), making the tool's purpose clear. However, it does not explicitly distinguish itself from sibling tools like find_tool or endpoint, and 'unified capabilities' is somewhat ambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: an agent should call this when it needs to know available capabilities, inputs, or providers. However, it does not provide explicit when-to-use guidance or alternatives, only the negative clarification 'No provider request.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Enrich a company from its domain, name, LinkedIn URL or a work email — treg picks the provider and names the one that served Use vendor to pin a provider. Returns outcome, normalized output, raw provider data and _meta.tried. Provider API charges are billed directly to your provider account.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | The company's name | |
| No | A work email address | ||
| domain | No | The employer's domain, no www and no @ | |
| vendor | No | Pin one vendor or endpoint id instead of routing | |
| website | No | The company's website | |
| waterfall | No | False stops at the first vendor instead of trying the next | |
| linkedin_url | No | https://www.linkedin.com/in/<slug> | |
| linkedin_handle | No | The <slug> from a LinkedIn URL, without the /in/ |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does well: it discloses automatic provider routing, the return payload components (outcome, normalized output, raw provider data, _meta.tried), and that provider API charges are billed to the provider account. The typo and lack of failure/rate-limit details keep it from a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose, but the sentence 'treg picks the provider and names the one that served Use vendor to pin a provider' is a run-on with missing punctuation and an unclear subject, forcing the agent to parse around the typo.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema covers return values, and the description covers routing and billing. However, with 8 optional parameters and no required field, the description never states that at least one identifier (domain, name, email, LinkedIn URL, etc.) must be provided, which is critical for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds little beyond the schema: 'Use vendor to pin a provider' is redundant with the vendor parameter's schema text, and it doesn't clarify combinations or any minimum identifier requirement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific operation ('Enrich a company') and lists several accepted identifier inputs (domain, name, LinkedIn URL, work email), which distinguishes it from companies_search. However, the phrase 'treg picks the provider and names the one that served Use vendor to pin a provider' is typo-laden and confusing, and it doesn't explicitly contrast with sibling enrichment tools like people_enrich.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use guidance or mention of alternatives. The only directive is 'Use vendor to pin a provider,' which is about parameter choice, not about when to choose this tool over companies_search or people_enrich. An agent is left to infer appropriate usage from the tool name and 'enrich' wording.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find companies by a free-text description, a name, an industry, a technology they use, or a domain — provider-native rows in companies Use vendor to pin a provider. Returns outcome, normalized output, raw provider data and _meta.tried. Provider API charges are billed directly to your provider account.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Free text describing who or what you are looking for | |
| name | No | The company's name | |
| limit | No | rows to return — THE price dial: most providers bill per row (default 10) | |
| domain | No | The employer's domain, no www and no @ | |
| vendor | No | Pin one vendor or endpoint id instead of routing | |
| country | No | ISO country code, where the provider supports it | |
| industry | No | An industry, as the provider names it | |
| waterfall | No | False stops at the first vendor instead of trying the next | |
| technology | No | A technology a company uses, e.g. snowflake |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does a good job: it discloses the return envelope (outcome, normalized output, raw provider data, _meta.tried), provider-native behavior, and the billing side effect. It could add auth or rate-limit context, but the disclosed cost behavior is valuable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with search criteria, then behavior, return shape, and cost. It is nearly clean, but the flow after '`companies` Use vendor' is slightly awkward and costs it a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers cross-cutting concerns well: search modes, vendor pinning, return envelope, and billing. With a rich output schema and detailed parameter descriptions, this is mostly complete, though explicit alternative-tool guidance and auth expectations would round it out.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3 and the description need not compensate. It adds only the vendor-pinning hint and billing context, which does not materially extend the parameter semantics already present in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds companies by free-text, name, industry, technology, or domain, which is a specific verb and resource. It does not explicitly distinguish itself from sibling tools like companies_enrich, so it misses the top score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus companies_enrich or people_search. The only usage-like advice is 'Use vendor to pin a provider,' which is parameter instruction rather than alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect an endpoint's arguments, provider documentation and availability before calling it.
| Name | Required | Description | Default |
|---|---|---|---|
| endpoint_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It conveys a read-only inspection behavior and lists the information returned, but it does not mention permissions, side effects, or explicitly state that the endpoint is not executed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the action, and contains no filler. Every word contributes to explaining the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter and an output schema, so the description covers the overall purpose and return categories. However, the endpoint_id parameter is undocumented in both the schema and the description, and there are no annotations, leaving the definition not fully self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description never mentions endpoint_id, its format, or how to obtain it. Since endpoint_id is required to invoke the tool, this is a significant gap that the description does not compensate for.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb, 'inspect', and a clear resource: an endpoint's arguments, provider documentation, and availability. The phrase 'before calling it' also distinguishes it from the sibling call_tool, so an agent can tell when this tool is relevant.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context by framing this as a pre-call inspection step. It does not explicitly name alternatives or exclusions, but the 'before calling it' instruction is enough to guide an agent toward using this before call_tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find provider endpoints when unified capabilities cannot meet the need. Searches API metadata, not people.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry behavioral context. It only states that it searches API metadata, but it does not disclose what a successful result looks like, whether it performs any side effects, or any limitations beyond the schema constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences with no fluff. It front-loads the core purpose and immediately clarifies scope with the 'not people' note.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given its simplicity (2 params, no nested objects) and the output schema existence, the description is minimally adequate. However, it does not explain what the output looks like or provide usage examples, leaving some ambiguity about query formulation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description does not explain the meaning of 'query' or 'limit' beyond their basic types. The query parameter's purpose is implied but not elaborated, and limit is left entirely to the schema defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to find provider endpoints when unified capabilities are insufficient. It explicitly distinguishes itself from people-related tools with 'Searches API metadata, not people.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context: use when unified capabilities cannot meet the need. It does not name specific alternatives, but the sibling list and the clarification about not searching people imply when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
How to reach one person: their work email, their phone when you ask for it, and whether an address you already hold is real. Use vendor to pin a provider. Returns outcome, normalized output, raw provider data and _meta.tried. Provider API charges are billed directly to your provider account.
| Name | Required | Description | Default |
|---|---|---|---|
| want | No | email | phone | verify | both. A phone costs several times an email, so it is only looked for when asked for. Passing an email you already hold and want='verify' checks it rather than finding one. (default email) | |
| No | A work email address | ||
| domain | No | The employer's domain, no www and no @ | |
| vendor | No | Pin one vendor or endpoint id instead of routing | |
| company | No | The employer's name | |
| full_name | No | The person's full name | |
| last_name | No | Family name; pair it with first_name | |
| waterfall | No | False stops at the first vendor instead of trying the next | |
| first_name | No | Given name; pair it with last_name | |
| linkedin_url | No | https://www.linkedin.com/in/<slug> | |
| company_website | No | The employer's website, when you have a URL rather than a bare domain | |
| linkedin_handle | No | The <slug> from a LinkedIn URL, without the /in/ |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral burden. It discloses the return shape (outcome, normalized output, raw provider data, _meta.tried), the fact that provider charges are billed directly, and the conditional behavior around phone lookups. It could mention failure handling or required identifiers, but for a read-style contact lookup this is solid transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four tight sentences with no filler. It front-loads the core purpose, then covers provider selection, return data, and billing. Every sentence adds useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, output, and billing, and an output schema exists, so return values are documented elsewhere. However, with 12 optional parameters and no annotations, it does not state what minimum identifiers are needed or how to choose among full_name, domain, email, etc. That leaves some invocation ambiguity for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains all 12 parameters in detail. The description reinforces vendor, phone, and verify semantics, but it adds little beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'How to reach one person', which states the tool's specific job: finding contact details for a single individual. It further specifies email, phone, and verification of an existing address, and the phrase 'one person' distinguishes it from sibling tools like people_search or people_enrich.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context: this is for reaching one person, and it notes that phone is only fetched when requested. It also advises using vendor to pin a provider. However, it does not explicitly name alternative tools or state when not to use this tool, though the 'one person' framing implies the distinction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Everything known about one person: title, employer, location, profile links. Use vendor to pin a provider. Returns outcome, normalized output, raw provider data and _meta.tried. Provider API charges are billed directly to your provider account.
| Name | Required | Description | Default |
|---|---|---|---|
| No | A work email address | ||
| domain | No | The employer's domain, no www and no @ | |
| vendor | No | Pin one vendor or endpoint id instead of routing | |
| company | No | The employer's name | |
| x_handle | No | @handle, or https://x.com/<handle> | |
| full_name | No | The person's full name | |
| last_name | No | Family name; pair it with first_name | |
| waterfall | No | False stops at the first vendor instead of trying the next | |
| first_name | No | Given name; pair it with last_name | |
| github_url | No | https://github.com/<login> | |
| scholar_url | No | https://scholar.google.com/citations?user=<id> | |
| linkedin_url | No | https://www.linkedin.com/in/<slug> | |
| linkedin_handle | No | The <slug> from a LinkedIn URL, without the /in/ |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It adds useful context by stating that the tool returns 'outcome, normalized output, raw provider data and _meta.tried' and that 'Provider API charges are billed directly to your provider account,' revealing that it invokes paid external providers. It does not, however, state whether the operation is read-only or what failure modes look like, and it omits any mention of the routing/waterfall behavior that the schema describes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four short sentences, front-loaded with the core purpose and followed by a parameter hint, return shape, and a critical billing caveat. It is tight and free of fluff, though it covers slightly more ground than the two-sentence ideal seen in top-tier tools.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity—13 optional parameters, vendor routing, and no annotations—the description gives a reasonable overview but leaves gaps. It introduces the vendor pinning concept and billing, and the output schema covers return values, but it does not explain prerequisites (e.g., whether at least one identifier must be supplied), the default routing/waterfall behavior, or how this tool differs from its many people-related siblings, so an agent may not fully know how to formulate a call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Since schema description coverage is 100%, the parameters are already well documented and the baseline is 3. The description adds little beyond the schema: 'Use vendor to pin a provider' loosely restates the schema's description of the vendor parameter ('Pin one vendor or endpoint id instead of routing') without adding new semantic detail, so the value added over the schema is marginal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Everything known about one person: title, employer, location, profile links,' which clearly communicates that this tool retrieves a comprehensive profile for an individual. However, it does not explicitly name or contrast sibling tools like people_search or people_identity_resolve, so an agent must infer the distinction from the phrase 'everything known' rather than being told when this tool is the right choice.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no explicit guidance on when to use people_enrich versus alternatives such as people_search or people_contact_find. It implies its place through 'Everything known about one person,' but does not state exclusions or scenarios, such as 'use people_search to find people, use people_enrich once you have an identifier.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Where a photo appears on the web, and who it is: pages carrying the exact image, and the social profiles among them. Use vendor to pin a provider. Returns outcome, normalized output, raw provider data and _meta.tried. Provider API charges are billed directly to your provider account.
| Name | Required | Description | Default |
|---|---|---|---|
| vendor | No | Pin one vendor or endpoint id instead of routing | |
| image_url | No | ||
| waterfall | No | False stops at the first vendor instead of trying the next |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does useful work by disclosing the output contract ('outcome, normalized output, raw provider data and _meta.tried') and the cost model ('Provider API charges are billed directly to your provider account'). It does not mention auth, rate limits, or failure behavior, but for a search-style tool the disclosed billing and raw-data behavior are meaningful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the tool's purpose. It delivers the key output and billing facts in four short sentences with no filler. Slight jargon like '_meta.tried' and 'normalized output' is acceptable because it matches the output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, output shape, vendor pinning, and billing, and an output schema exists to document return values. However, it omits usage routing versus siblings and leaves the primary image_url parameter under-explained. For a tool with no annotations and a meaningful sibling set, this is adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%: vendor and waterfall are documented, while image_url has an empty schema description. The description reinforces vendor selection but does not clarify the core image_url input or its expected format. The parameter name and the phrase 'Where a photo appears' make the intent inferable, so this is a moderate gap rather than a severe one.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a reverse-image lookup: it finds web pages carrying an exact image and the social profiles among them. It uses descriptive phrasing rather than a verb like 'find', but the resource and outcome are unmistakable. It does not explicitly differentiate itself from the sibling social_profile tool, but its image-based input and page-plus-profile output distinguish it in practice.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to choose this tool over siblings such as people_search, social_profile, or people_identity_resolve. The only directive, 'Use vendor to pin a provider', is operational parameter guidance rather than use-case guidance. There is no mention of when this tool is appropriate or when an alternative should be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Identity resolution: one person's profiles across platforms, resolved into a single set. Give any one of them — LinkedIn, GitHub, X, Hugging Face, Scholar, an email — and get the rest. Use vendor to pin a provider. Returns outcome, normalized output, raw provider data and _meta.tried. Provider API charges are billed directly to your provider account.
| Name | Required | Description | Default |
|---|---|---|---|
| No | A work email address | ||
| domain | No | The employer's domain, no www and no @ | |
| vendor | No | Pin one vendor or endpoint id instead of routing | |
| company | No | The employer's name | |
| x_handle | No | @handle, or https://x.com/<handle> | |
| full_name | No | The person's full name | |
| last_name | No | Family name; pair it with first_name | |
| waterfall | No | False stops at the first vendor instead of trying the next | |
| first_name | No | Given name; pair it with last_name | |
| github_url | No | https://github.com/<login> | |
| scholar_url | No | https://scholar.google.com/citations?user=<id> | |
| linkedin_url | No | https://www.linkedin.com/in/<slug> | |
| huggingface_url | No | https://huggingface.co/<login> | |
| linkedin_handle | No | The <slug> from a LinkedIn URL, without the /in/ |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the return shape ('outcome, normalized output, raw provider data and _meta.tried') and a significant behavioral trait: 'Provider API charges are billed directly to your provider account.' This goes beyond a basic one-liner, though it doesn't cover every operational behavior such as rate limits or failure semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three tightly packed sentences with no filler. It front-loads the core concept, then gives input requirements, references the vendor option, and lists output components and billing context. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a 14-parameter tool with full schema coverage and an output schema present, the description covers the essential usage narrative: what the tool does, what it returns, how to constrain provider selection, and a billing caveat. It is slightly incomplete in not differentiating from nearby sibling tools, but overall it is sufficient for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each of the 14 parameters is already documented in the input schema. The description adds the high-level insight that providing any one identifier is sufficient to resolve the rest, but it does not add per-parameter meaning beyond what the schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb phrase ('Identity resolution') and states the exact resource: one person's profiles across platforms resolved into a single set. It clearly defines the input/output contract ('Give any one of them... and get the rest') and distinguishes itself from sibling tools like people_search or social_profile by focusing on cross-platform merging rather than search or enrichment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: use this tool when you have any one profile identifier (LinkedIn, GitHub, X, etc.) and need the full consolidated set. It also notes the optional 'vendor' parameter to pin a provider. It does not explicitly list when-not-to-use or name alternatives like people_search/people_enrich, so it misses an explicit exclusion clause.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A list of people you did not have: from a description — a role, a company, a place — or from a source that names them, such as a repository, a paper, a Scholar profile or a company page. Use vendor to pin a provider. Returns outcome, normalized output, raw provider data and _meta.tried. Provider API charges are billed directly to your provider account.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Free text describing who or what you are looking for | |
| limit | No | how many people to return — the price dial on per-row vendors (default 25) | |
| title | No | the role, as a company would write it | |
| vendor | No | Pin one vendor or endpoint id instead of routing | |
| country | No | ISO country code, where the provider supports it | |
| keywords | No | skills, topics or domain terms the person must match ('microservices', 'match analysis') — the SUBSTANCE of most briefs; a provider with no keyword field answers a looser question and ranks below one that has it | |
| location | No | free text place; providers normalise it differently | |
| full_name | No | The person's full name | |
| seniority | No | director, vp, c_suite, senior, entry | |
| waterfall | No | False stops at the first vendor instead of trying the next | |
| source_url | No | A page that names people: a repository, a paper, a LinkedIn company page, a Crunchbase profile | |
| company_name | No | A company name, to read its people and coverage | |
| company_domain | No | employer domain, to search inside one company |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that provider API charges are billed directly to the provider account, which is a key behavioral trait. It also mentions the return fields (outcome, normalized output, raw provider data, _meta.tried), giving insight into the response. However, it does not elaborate on error handling, rate limits, or what happens when the waterfall stops (only implied in the schema). The statement about billing is valuable and specific.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately concise, two sentences plus a billing note, but it is dense and front-loaded with the core purpose. It mentions return payload fields and billing behavior, which are useful. There is no wasted verbiage, though the billing info could be seen as slightly tangential but is important for user awareness. The structure is good; the core purpose comes first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (13 params, no required ones) and the presence of an output schema (not shown here, but indicated), the description covers the essential behavioral and selection aspects. It explains the input modes, vendor control, waterfall behavior (via parameter note), and cost implication. It does not detail return format since output schema exists. It is complete enough for an agent to invoke correctly, though some nuances like exact vendor selection logic are left to the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all 13 parameters have descriptions. The tool description adds context that goes beyond the schema: it explains that 'keywords' is 'the SUBSTANCE of most briefs' and explains how providers without keyword fields are ranked. It also explains the purpose of 'limit' as 'the price dial on per-row vendors'. This adds meaningful semantic guidance that the bare schema descriptions lack, so the description compensates well despite the schema's heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: finding people from a description (role, company, place) or from a source that names them. It distinguishes the tool's broad capability and explicitly mentions vendor pinning and return payload fields, making it distinct from siblings like people_enrich (which likely enriches known people) and people_identity_resolve (which resolves identities). The verb 'search' is implied by the name and context, and the resource is 'people', with specific input modes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance on what inputs to use ('a role, a company, a place' or 'a source that names them'), and how to control provider ('Use vendor to pin a provider'). It also hints at the 'waterfall' behavior implicitly via the parameter description, but does not explicitly contrast with siblings or state when not to use it. However, it gives enough context for the agent to choose it over enrichment/resolution tools, though it could mention alternatives for known people (e.g., people_contact_find).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0call_toolcapabilitiescompanies_enrichcompanies_searchendpointfind_toolpeople_contact_findpeople_enrichpeople_from_imagepeople_identity_resolvepeople_searchsocial_profileScored across 12 tools
The people_* family is mostly distinct, but social_profile, people_enrich, and people_identity_resolve all accept a single person identifier and return profile-related data, so an agent needs to read descriptions carefully. The meta tools (find_tool, endpoint, call_tool) are clearly separated.
Most domain tools follow a clear people_/companies_ prefixed snake_case pattern. Minor deviations include social_profile lacking the people_ prefix and meta tools mixing noun forms (capabilities, endpoint) with verb_noun forms (find_tool, call_tool).
12 tools is well within the ideal range for a multi-provider data router: 8 domain operations plus 4 discovery/execution tools. Each tool has a clear role, and none feel redundant.
People workflows are comprehensively covered: search, social profile, enrich, identity resolution, contact finding, and image-based lookup. Companies have search and enrich, and the capabilities/find_tool/endpoint/call_tool layer prevents dead ends by allowing access to provider-specific endpoints.
Enrich, search, assess, and manage threat intelligence through 80+ typed MCP tools.
Remote MCP server to enrich company profiles with structured B2B data and confidence scores.
Enrich and search people and companies, resolve identities, and enrich IP addresses.
Identity resolution MCP server for phone/email lookups across 31+ services. Global + India coverage.
social_profileA
One person's public profile on whatever platform a handle belongs to: LinkedIn, X, Instagram, TikTok, YouTube, GitHub and the rest. Give a profile URL, or a platform and a handle. Use vendor to pin a provider. Returns outcome, normalized output, raw provider data and _meta.tried. Provider API charges are billed directly to your provider account.
Output Schema
No output parameters
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden and does it well: it states the return payload includes outcome, normalized output, raw provider data, and _meta.tried, and it warns that provider API charges are billed to the user's provider account. This is meaningful behavior beyond what the schema alone reveals. It could go further on auth or fallback behavior, but the default waterfall is at least hinted at by the vendor-pinning instruction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and efficiently front-loaded: the purpose comes first, followed by input modes, provider control, and return/billing notes. Every sentence earns its place, though the first sentence is slightly long and could be tightened.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no required parameters and a rich output schema, the description covers the key operational facts: what it returns, how to identify a target, how to control the vendor, and cost implications. It does not mention precedence when both profile_url and platform+handle are supplied, but that is a minor gap given the schema and output schema context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3, but the description adds value by explaining the relationship between parameters: profile_url OR platform+handle are alternative ways to identify the target, and vendor pins the provider. This usage-level guidance goes beyond the individual property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies what the tool does: it returns one person's public profile across many specified platforms, and explains the two input modes. It is specific enough to separate it from broader people_search or people_enrich tools, though it does not explicitly name a sibling to contrast with.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives practical invocation guidance: provide a profile URL, or a platform and handle, and optionally use vendor to pin a provider. However, it never says when to choose this tool over siblings like people_search or people_identity_resolve, so the usage context is more implied than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.