diffbot-mcp

Official

by diffbot

Overview Schema Source Related Servers Discussions Admin

Python

Hybrid

Search Organizations

search_organizations

Read-onlyIdempotent

Search structured company data by industry, location, headcount, revenue, founding date, public status, founder, investor, acquirer, or parent company for prospect lists and market maps.

Instructions

Company and organization structured search over the Diffbot Knowledge Graph. Prefer for prospect lists, market maps, competitor sets, and firmographic facts on a market or named company(ies). Filter by industry, location, headcount, revenue, founding date, public status, founder, investor, acquirer, parent company. Prefer over a generic web search when answer involves structured company data. For investment data use search_deals; for people use search_people. 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_organizations"
  }
}

Input Schema

Name	Required	Description
`city`	No	HQ city or cities
`name`	No	Company name(s) or homepage domain
`near`	No	Place and radius, e.g. 'Austin 30mi'
`size`	No	Max rows
`sort`	No	Only if ordering is the question
`facet`	No	Bucket by field, e.g. categories.name
`offset`	No	Rows to skip
`region`	No	HQ state/region
`series`	No	Funding round raised, e.g. 'Series B'
`country`	No	HQ country
`founded`	No	Year or range, e.g. '2015-2020'
`founder`	No	Founder name: companies they founded
`part_of`	No	Index or group, e.g. 'S&P 500'
`revenue`	No	Range, e.g. '10M-75M', '1B+'
`industry`	No	Industries (OR); free text ok
`investor`	No	Investor: its portfolio
`employees`	No	Range, e.g. '50-500', '<=20', '500+'
`is_public`	No	Publicly traded
`similar_to`	No	Anchor company for lookalikes
`subsidiary`	No	Subsidiary name: its parent
`acquired_by`	No	Acquirer: its acquisitions
`descriptors`	No	Free-text niche, e.g. 'plant-based'
`primary_industry`	No	False: also match secondary tags

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 9, 2026

TDQS

A4.1/5.0

Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered upstream. The description adds source context (Knowledge Graph, structured data) but says nothing about result volume, pagination behavior across the 23 filters, or any cost/latency characteristics. Adequate but not rich beyond annotations.

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?

Front-loaded with purpose, then use cases, then routing, then docs link — a sensible order with no filler. The mid-sentence field enumeration is somewhat redundant given full schema coverage, costing a bit of tightness.

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?

With an output schema present and 100% parameter coverage, the description need not explain returns; it covers purpose, use cases, and sibling routing. It omits any note on combining filters or interpreting faceted results, which for a 23-parameter search tool is a minor remaining gap.

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?

Schema description coverage is 100%, so every filter is documented in the schema itself, and the description's enumeration (industry, location, headcount, revenue, founding date, public status, founder, investor, acquirer, parent company) largely restates those fields. It does not add filter-composition semantics (e.g., how multiple filters combine) beyond what the schema implies, so baseline 3 applies.

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?

States a specific verb and resource ('Company and organization structured search over the Diffbot Knowledge Graph') plus concrete use cases (prospect lists, market maps, competitor sets, firmographic facts). An agent can immediately distinguish it from search_deals and search_people, which are named explicitly.

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?

Gives explicit when-to-use ('prefer for prospect lists, market maps...'), an explicit alternative to avoid ('prefer over a generic web search when answer involves structured company data'), and routes to specific siblings ('For investment data use search_deals; for people use search_people'). Little is left to inference.

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

Deploy Server