diffbot-mcp

Official

by diffbot

Overview Schema Source Related Servers Discussions Admin

Python

Hybrid

Search People

search_people

Read-onlyIdempotent

Find people by name, job title, employer, school, skills, location, or net worth in the Diffbot Knowledge Graph. Use it for leadership, executive, alumni, and skill-based people lookups.

Instructions

People structured search over the Diffbot Knowledge Graph. Prefer for leadership teams, executive and role lookups, alumni lists, skill-based sourcing, and profile facts on a named person. Filter by job title, employer, employer industry or size, school, major, skills, residence, nationality, or net worth. Prefer over a generic web search when the answer involves structured people data. Covers people with a public professional presence only. For companies use search_organizations. API docs: https://www.diffbot.com/docs/dql/

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "search_people"
  }
}

Input Schema

Name	Required	Description
`city`	No	Residence city or cities
`name`	No	Person name(s), exact
`size`	No	Max rows
`sort`	No	Only if ordering is the question
`major`	No	Field of study
`skill`	No	Skills (OR)
`title`	No	Job titles (OR); C-suite expanded
`degree`	No	Degree, e.g. 'MBA'
`gender`	No	Gender
`offset`	No	Rows to skip
`region`	No	Residence state/region
`school`	No	Institution name
`country`	No	Residence country
`current`	No	False: include past jobs
`employer`	No	Employer name
`language`	No	Language spoken
`net_worth`	No	Minimum net worth, e.g. '1B'
`nationality`	No	Nationality as country name
`job_category`	No	Occupation group, e.g. 'Business', 'Religion'
`job_location`	No	City or country where the job is
`leadership_of`	No	Company domain or name: its CEO and founders
`school_location`	No	City or country of the school
`employer_country`	No	Employer HQ country
`employer_industry`	No	Employer's industry; free text ok
`employer_employees`	No	Employer headcount range, e.g. '<=50'

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 9, 2026

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered; the description adds the substantive behavioral caveat that coverage is limited to people with a public professional presence. It does not discuss result limits, pagination behavior, or cost/quota, which would matter for a 25-filter KG query.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded in the first clause, alternatives and boundaries follow, and the docs link is appended last where it belongs. The middle capability list is dense but each item maps to a real use case; only minor redundancy between "prefer for role lookups" and the later "prefer over generic web search" sentence.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 25-parameter, zero-required search tool with full schema coverage, an output schema, and complete annotations, the description supplies the missing decision layer: what it is for, which sibling to use instead, and its data-coverage limit. The only shortfall is that it never addresses pagination or default result size, which an agent must otherwise infer from the schema's size/offset defaults.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema description coverage the schema already defines every one of the 25 parameters, so the baseline applies. The description groups the filterable dimensions (title, employer, industry/size, school, major, skills, residence, nationality, net worth), which helps an agent discover capability, but it omits several schema filters (leadership_of, job_category, current, job_location) and adds no syntax or combination guidance beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

"People structured search over the Diffbot Knowledge Graph" states a specific verb and resource, then the following sentences enumerate the concrete query shapes it supports (leadership teams, role lookups, alumni lists, skill sourcing, profile facts). It also names the boundary against search_organizations, so an agent can separate the two people/company tools without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit positive cases (leadership, executives, alumni, skills, named-person facts), an explicit routing rule ("For companies use search_organizations"), and an explicit preference condition versus generic web search. That covers when to use, when to use a sibling, and when to use a different tool class entirely.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server