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

Company and person discovery

Use revor_create_webset to describe target companies or people. Set target_kind to company or person; person searches can specify role, seniority, geography, industry background, and current company. Available counts depend on the account membership tier:

The service never silently reduces an out-of-tier request. It returns an explicit membership-tier error instead. A successful creation returns both webset.id and preparation_job.id.

• revor_get_job only confirms whether preparation started successfully.
• revor_find_more_webset adds count targets on top of the existing qualified baseline. It requires a stable idempotency_key; use revor_get_job afterward to confirm the new round was queued.
• revor_get_webset reports the full discovery status and progress. progress.verified covers the current run only, while progress.qualified describes the result pool and may include unreleased overflow.
• revor_get_webset_strategy reads criteria and the search strategy early. Check criteria_ready and strategy_ready; the prospect list does not need to be complete.
• revor_list_webset_items reads company results; results may be marked provisional while discovery is running. After completion, page until has_more=false to obtain the final visible list.
• revor_list_websets returns 20 entries by default and accepts a maximum limit of 100.

An item's match.score is the 0–100 overall weighted fit score, and match.status places it in the full, partial, or rejected band. Both full and partial are qualified results. In a one-criterion Webset, the overall score may equal that criterion's confidence multiplied by 100. entity.name is a display label; MCP clients should use the item id as the stable key and use the website to distinguish companies or regional legal entities with the same name.

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:

Example prompt:

TextCopy
Find 100 procurement or supply-chain leaders at industrial-automation companies in Germany. Create a person prospect list, follow its progress, and page through qualified results in compact mode.

Accounts, channels, and outreach

Call revor_list_connect_accounts with the intended channel and can_send=true before outreach, then use a returned account ID. revor_send_outreach and revor_like_linkedin_post perform real external actions. The AI client should confirm the recipient, channel, and content with the user before calling and retain the same idempotency_key for safe retries.

MCP and the API share account-wide limits by operation type; switching API keys or protocols does not grant another allowance. Request rate, active-job concurrency, and credits are enforced independently. See Rate limits, concurrency, and retries for tier allowances, operation mapping, response headers, and retry guidance.

Public-information research

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

Main inputs:

Example prompt:

TextCopy
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:

Example prompt:

TextCopy
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. A candidate's trade-row count proves only that the name is queryable; it does not establish the legal entity's identity.

The same short name can aggregate similarly named entities in several countries or regions. Before citing results, verify the candidate's country, company ID, and downstream records. If a full legal name returns no match, a shorter name can broaden recall, but it must remain an unverified candidate until checked.

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:

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

Discover customs companies

Use revor_customs_discover_companies when the user does not already know a company name. Set company_role=importer to find buyers or importers and company_role=exporter to find suppliers or exporters. Filter by an HS code or product keywords, origin or destination country, and a date range.

An HS code must contain 2, 4, 6, 8, or 10 digits. Each call accepts one code or chapter prefix only; comma-separated values, whitespace-separated lists, and ranges such as 84-85 are rejected. Run separate searches for multiple categories. Use ISO 3166-1 alpha-3 country codes such as CHN and BRA; a valid alpha-2 input is also normalized to alpha-3.

If the company is already known, use revor_customs_company_candidates to verify its name and query route before calling a company-level customs tool. Use revor_customs_discover_companies to discover a list only when the target companies are not yet known.

Example prompt:

TextCopy
Find companies that imported HS 8429 construction machinery from China into Brazil during the last year. Return the top 20 by trade count, without asking me for a company name first.

Customs trade queries

The billable customs tools share these main inputs:

Billable queries settle credits from rows actually returned; a zero-row result ultimately consumes 0 credits. Current row-level magnitudes are below. The completed job's billing.charged_credits is the source of truth:

A complete report bills the actual rows in all four sections; a single-purpose tool bills only its dimension. Job creation temporarily reserves available balance from page_size, so insufficient balance can prevent creation even if the eventual result would contain zero rows; unused reservation is released at settlement. There is currently no pre-query dry-run estimate. Lower page_size to control exposure and inspect billing after completion.

Asynchronous jobs

Prospect-list preparation, research, contact, and customs tools use jobs. Research, contact, and customs creation tools wait up to the service's synchronous-wait limit (20 seconds by default), so fast jobs can return a completed item in the original tool call. Configure the client's per-tool timeout to at least 30 seconds so it does not time out during a normal server wait. The wait listens for a completion event instead of repeatedly querying job state, reducing unnecessary polling requests and polling-limit usage. Prospect-list discovery remains asynchronous because it commonly runs longer than this window.

Creation tools return the job as item and provide an exact next_action. If the synchronous wait finishes the job, next_action is null and the result is already available. Otherwise, save item.id, wait for next_action.retry_after_ms, and call revor_get_job with next_action.arguments (equivalent to { "job_id": item.id }). Continue with the same job ID until its status is succeeded, failed, or cancelled. Do not submit the original business request again just to check progress, because that may create a new job.

revor_cancel_job only guarantees cancellation for queued or scheduled jobs. A running job may already have called an external service or performed a side effect, so the tool returns job_already_running instead of claiming that it was cancelled.

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.

An API-key rate limit at the MCP HTTP entry point uses a JSON-RPC error rather than a REST error body:

JSONCopy
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32001,
    "message": "REVOR AI request rate limit exceeded.",
    "data": {
      "code": "api_key_rate_limit_exceeded",
      "request_id": "...",
      "retry_after_ms": 60000
    }
  },
  "id": null
}

The HTTP response also includes Retry-After. A tool-execution rate limit exposes the delay as error.retry_after_ms in the tool error. Clients that cannot read HTTP headers should use that field and must not immediately retry in parallel.