MCP tool reference

REVOR AI MCP tools are named by business capability. They return stable REVOR AI fields, job states, and billing information without exposing internal implementation details or third-party services.

Tool list

Tool	Purpose	Billing
`revor_whoami`	Check the authorized account and connection permissions.	Free
`revor_research_public_web`	Research companies, markets, or recent developments from public information.	API pricing rules
`revor_find_contacts`	Find business contacts by verified company domain and role.	API pricing rules
`revor_customs_company_candidates`	Resolve a company name that can be used for customs queries.	Currently free
`revor_customs_full_report`	Create a report covering counterparties, categories, trends, and countries.	Based on returned data
`revor_customs_counterparties`	Query major trading counterparties.	Based on returned data
`revor_customs_categories`	Query major products or HS Code categories.	Based on returned data
`revor_customs_trend`	Query monthly, quarterly, or yearly trade trends.	Based on returned data
`revor_customs_countries`	Query origin or destination country distribution.	Based on returned data
`revor_create_webset`	Create a company Webset from a natural-language target profile.	API pricing rules
`revor_list_websets`	Page through the authorized account's Websets.	No repeat charge
`revor_get_webset`	Get Webset status, progress, and criteria.	No repeat charge
`revor_list_webset_items`	Page through ranked Webset results.	No repeat charge
`revor_get_job`	Retrieve a job's status, result, and billing details.	No repeat charge

Target-company discovery (Websets)

Use revor_create_webset to describe target companies by industry, geography, product, business model, and required qualifications. The current creation contract targets 25 companies and returns both webset.id and preparation_job.id.

revor_get_job only confirms whether preparation started successfully.
revor_get_webset reports the full discovery status and progress.
revor_list_webset_items reads company results; results may be marked provisional while discovery is running.
revor_list_websets returns 20 entries by default and accepts a maximum limit of 100.

Results use cursor pagination. Pass the previous response's next_cursor unchanged to retrieve the next page, and stop when has_more is false. Detail modes have these page limits:

`detail`	Content	Maximum `limit`
`compact`	Core company fields and match outcome	50
`standard`	Adds match counts and criteria summaries	25
`full`	Adds full criteria reasoning and public evidence	10

Example prompt:

Text
Find 25 companies in Germany that manufacture industrial heat pumps and sell through international distributors. Create a Webset, follow its progress, and page through qualified results in compact mode.

Public-information research

Use revor_research_public_web for company background, products, markets, news, and public financial information.

Main inputs:

Field	Description
`queries`	One or two focused research questions.
`search_limit`	Desired results per query, up to 10.
`category`	Optional information type, such as company, news, financial report, or people.
`include_domains`	Optional domains to use as the research scope.
`user_location`	Optional two-letter country or region code.

Example prompt:

Text
Research example.com's main products, target customers, and major developments during the last year, with public sources.

Company contacts

revor_find_contacts requires a verified company website domain.

Main inputs:

Field	Description
`domain`	The company's website domain, not a search-results URL.
`positions`	Optional job titles or business functions.
`limit`	Maximum number of contacts.
`locale`	Optional result language: `en` or `zh`.

Example prompt:

Text
Find up to 10 procurement, supply-chain, and international-business contacts at example.com.

Resolve a customs company name

Customs queries depend on an accurate registered or trading name. Call revor_customs_company_candidates first and select the correct candidate before starting a billable query.

Main inputs include the company name, company role, imports or exports catalog, start date, and end date. This discovery tool currently does not consume credits.

Example prompt:

Text
Resolve the customs company name for Example Company as an importer during 2025.

Customs trade queries

The billable customs tools share these main inputs:

Field	Description
`company_name`	A confirmed, exact company name.
`company_role`	The company's role in the records: `importer` or `exporter`.
`catalog`	Optional imports or exports catalog.
`start_date` / `end_date`	Date range in `YYYY-MM-DD` format.
`page_size`	Results per page, up to 20.
`period_unit`	Trend period: months, quarters, or years.
`filters`	Optional HS Code, product description, or country filters.

Billable queries settle credits from the amount of data returned. Use the complete report when you need all four trade dimensions. Use a single-purpose tool when you only need one dimension.

Asynchronous jobs

Webset preparation, research, contact, and customs tools commonly return a job object.

Status	Meaning
`queued`	The job was created and is waiting.
`running`	The job is being processed.
`succeeded`	The `result` and `billing` details are ready.
`failed`	The job failed and includes a public error code.
`cancelled`	The job was cancelled.

If a job is not complete, call revor_get_job with its job_id. Do not submit the original business request again just to check progress, because that may create a new job.

Idempotency and retries

Every action tool requires an idempotency_key. Reuse the same value only when retrying the exact same input after a network interruption. Use a new value for a new operation. Reusing a key with different input returns idempotency_conflict and does not start a second task. AI clients should generate and retain this value automatically.

Errors and privacy

Tools return stable REVOR AI public error codes and a request_id. They do not expose internal call chains, credentials, debug data, or raw upstream responses. If a call fails, check the input, account permissions, credits, and usage limits first. Keep the request_id and job ID when contacting support.