Tool reference

Start with MCP connection setup. Call tools/list to discover the schemas advertised by the server you are connected to. These tools return the same business data as the HTTP API.

search_companies

Find distinct companies with relevant evidence. Supports natural-language query planning, exact filters, and optional background processing.

Argument	Type	Default / requirement
`query`	string	Required; 1–500 characters
`filters`	object	`{}`; see supported filters below
`limit`	integer	`10`; minimum 1, maximum set by the subscription
`cursor`	string or null	Omit on the first page
`background`	boolean	`false`; use `true` to retrieve results later
`request_key`	string	Required unless `Idempotency-Key` is supplied as a header

{
  "name": "search_companies",
  "arguments": {
    "query": "Companies seeking charging equipment",
    "filters": { "countries": ["CA"], "exclude_domains": ["example.com"] },
    "limit": 10,
    "background": true,
    "request_key": "charging-prospects-1"
  }
}

The examples on this page are the params object inside a JSON-RPC tools/call request, not complete HTTP requests. Read usage.id from a pending result and call get_usage to retrieve it. Completed results contain companies, supporting observations, coverage, and next_cursor.

Supported filters

Filter	Accepted values
`countries`	Array containing `CA` and/or `US`; observation location, not headquarters
`kinds`	Array of `procurement_request`, `facility_expansion`
`demand_classes`	Array of `explicit_request`, `proxy`, `structural`
`occurred_after`, `observed_after`	ISO 8601 timestamp strings
`company_ids`, `exclude_company_ids`	Up to 100 positive integer IDs per field
`domains`, `exclude_domains`	Up to 100 hostnames per field; no URLs or email addresses

Values within a field are OR; different fields are AND. Exclusions win. Empty arrays do not restrict. Domain matching normalizes case, whitespace, and a trailing dot; it does not remove www or merge subdomains. Only currently evidenced domain relationships match.

get_company

{ "name": "get_company", "arguments": { "id": 123 } }

id is a required positive integer returned by search. Returns company with identity, supported domains, and up to three recent observations. This is an unmetered, subscription-authorized read, not a full profile or a fresh lookup. company_not_found means no deliverable company was found.

search_observations

{ "name": "search_observations", "arguments": { "query": "charging", "limit": 10, "request_key": "charging-evidence-1" } }

Accepts query, filters, limit, cursor, and request_key with the same basic types as company search. Filters support countries, kinds, demand classes, and the two timestamp fields only. Company lists, domain lists, and background are not accepted here. This search does not use company-search query planning. Returns individual observations rather than grouped companies.

get_observation

{ "name": "get_observation", "arguments": { "id": 456 } }

id is a required integer from a returned observation. Returns observation and its currently permitted evidence. Unmetered, but requires subscription access. Does not start new research.

create_usage

{ "name": "create_usage", "arguments": { "query": "charging", "limit": 10, "request_key": "background-evidence-1" } }

Queues an observation search, using the same inputs as search_observations. Returns an operation to poll with get_usage. For background company results, use search_companies with background: true instead.

get_usage

{ "name": "get_usage", "arguments": { "id": 789 } }

{ "name": "get_usage", "arguments": {} }

Optional id is an integer. With an ID, returns the account-owned operation’s status or results; without it, returns subscription usage and limits. Neither read is metered. An ID from another account returns usage_not_found.

diagnostic

{ "name": "diagnostic", "arguments": {} }

Requires an Idempotency-Key header; there is no request_key argument. Returns subscription plan/status and metering information. It consumes one request unit for a new successful operation. Prefer unmetered tools/list to check connectivity or get_usage to check allowance.

Handle responses safely

Read result.structuredContent. Text-only clients can parse the equivalent JSON in result.content.
Check result.isError and structuredContent.error.code; HTTP success alone is not tool success.
Reuse a request key only for identical retries. A next page uses a new key with unchanged query, filters, and limit, plus the returned cursor.
Stop on subscription or capacity errors. Inspect the structured retry guidance when supplied.
Do not describe partial or empty coverage as proof that no prospect exists.

OAuth, change-feed tools, contact enrichment, and automated outreach are not implemented.

​search_companies

​Supported filters

​get_company

​search_observations

​get_observation

​create_usage

​get_usage

​diagnostic

​Handle responses safely