Skip to main content
Glama
Sign In
diffbot-mcp

diffbot-mcp

Official
by diffbot
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

Run DQL Query

dql
Read-onlyIdempotent

Runs raw Diffbot Knowledge Graph queries for entity types and query shapes typed search tools don't cover, including products, patents, job posts, facets, cross-entity filters, and CSV exports.

Instructions

Runs a raw DQL query against the Diffbot Knowledge Graph. Prefer for entity types and query shapes the typed search tools do not cover: products, patents, job posts, facet aggregations, cross-entity queries, or an id filter from resolve_entities. Each typed tool returns the DQL it ran, which can be refined here. Conditions on one nested list object go inside one {} block, e.g. employments.{employer.name:X isCurrent:true}. Confirm field paths and taxonomy spellings with dql_ontology, since an unknown path is silently ignored. Do not add a sort unless ordering is the question. Check hit counts with dql_probe before pulling rows. For a CSV file, do not page rows: GET https://kg.diffbot.com/kg/v3/dql?token=..&format=csv&size=&exportspec=&query= for a download URL or save to disk. API docs: https://www.diffbot.com/docs/dql/

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "query": "<query>"
    },
    "name": "dql"
  }
}

Input Schema

NameRequiredDescriptionDefault
sizeNoMax rows or buckets
queryYesDQL, starting with type:X
fieldsNoCSV columns as 'path,Label;path,Label'; default per entity type
formatNo'json' for full records; add get:a,b to query to limitcsv
offsetNoRows to skip
hits_onlyNoCount only

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior, and the description adds meaningful operational context beyond that: unknown field paths are silently ignored, nested-list conditions require one {} block, and CSV extraction should use a direct GET for a download URL instead of paging. These details materially reduce misuse risk.

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, followed by dense but relevant usage rules and caveats. Every sentence contributes useful guidance, though the single long paragraph could be more clearly segmented for readability.

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

Completeness5/5

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

Given the query complexity, fully described input schema, annotations, and existing output schema, the description covers the missing decision and syntax context: when to use it, how nested conditions work, how to validate paths, when to probe counts, and how to handle CSV downloads. This is complete enough for an agent to invoke the tool correctly and safely.

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

Parameters4/5

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

Schema coverage is 100%, so the schema already documents each parameter and the baseline is 3. The description adds query-language semantics (nested-list block syntax, field validation via dql_ontology, CSV exportspec/size usage) and a no-paging caveat, though it does not significantly elaborate on offset or hits_only 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?

States 'Runs a raw DQL query against the Diffbot Knowledge Graph' with a specific verb and resource, then explicitly distinguishes the tool from typed search tools by listing uncovered entity types and query shapes. An agent can identify its role without reading the schema first.

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 preference cases such as products, patents, job posts, facet aggregations, cross-entity queries, and id filters from resolve_entities. It also points to siblings for prerequisites (`dql_ontology` for field paths and `dql_probe` for hit counts), and adds practical rules like not sorting unless ordering matters and not paging CSV rows.

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

Deploy Server

Other Tools