Skip to main content
Glama
fairquery-contact-enricher

fairquery-contact-enricher

Official

Get results of a background enrichment run (free)

get_enrichment_results
Read-onlyIdempotent

Poll an async domain enrichment run started by enrich_domains to check status and page through result rows while the run is still in progress.

Instructions

WHAT: Read the status and result rows of an enrich_domains run started with waitForFinish=false, one page at a time. WHEN TO USE: after enrich_domains returned run.run_id, to poll until finished is true and page through the rows; rows already written are returned while the run is still RUNNING. WHEN NOT TO USE: to start an enrichment (enrich_domains) or to preview cost (normalize_domains). Cannot read runs of other Actors. BEHAVIOR: GET requests to the Apify API only (actor, run, dataset); never starts, aborts or re-bills a run. Typically <1 s. Poll every 10-30 s; a run works on 5 domains at a time, ~2-10 s each. COST: free; needs the APIFY_TOKEN that started the run. Reading charges no Actor event (the run was billed per enriched domain when it ran). RETURNS: run (run_id, status, finished) plus one page of the same rows enrich_domains returns; Errors: APIFY_TOKEN_MISSING, RUN_NOT_FOUND, RUN_NOT_FOR_THIS_ACTOR, APIFY_TOKEN_INVALID, APIFY_RUN_LOOKUP_FAILED / APIFY_DATASET_READ_FAILED (retryable). PARAMETERS: runId is run.run_id from enrich_domains (also in the Apify console URL). status is READY | RUNNING | SUCCEEDED | FAILED | ABORTED | TIMED-OUT; finished=true for the last four, after which total no longer changes. A FAILED or TIMED-OUT run still returns the rows it wrote. offset/limit page the rows in write order; total counts all rows written so far, so keep calling with nextOffset until it is null and finished is true. EXAMPLE: {"runId":"a1B2c3D4e5F6g7H8i"} -> {"run":{"status":"SUCCEEDED","finished":true},"count":1,"total":1,"items":[{"type":"domain","domain":"apify.com",...}]}

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": {
      "runId": "<runId>"
    },
    "name": "get_enrichment_results"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoOptional page size, integer 1-1000, default 100. Example: 250
runIdYesRequired. Apify run ID (letters and digits) from enrich_domains run.run_id. Example: "a1B2c3D4e5F6g7H8i"
offsetNoOptional integer >= 0, default 0; use nextOffset from the previous page. Example: 100

Output Schema

NameRequiredDescriptionDefault
runYesrun_id, status, finished, dataset_id, started_at, finished_at, console_url
countYesRows in this page
itemsYesDataset rows: type=domain or type=error
totalYesRows written by the run so far
nextOffsetYesOffset of the next page, or null

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv1.1.0

TDQS

A4.9/5.0
Behavior5/5

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, and the description adds substantial context beyond them: GET-only calls, never starts/aborts/re-bills, sub-second typical latency, poll cadence of 10-30 s, processing throughput (5 domains at a time, ~2-10 s each), token/auth requirements, cost model, and the full error-code list including which failures are retryable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Long but fully front-loaded and labeled (WHAT/WHEN/BEHAVIOR/COST/RETURNS/PARAMETERS/EXAMPLE). Every section carries distinct information for a polling tool, and the one-line JSON example compactly conveys the response shape.

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?

Despite an output schema existing, the description still covers status/finished semantics, that FAILED or TIMED-OUT runs return partial rows, and the error taxonomy. Combined with annotations, schema, and output schema, an agent has everything needed to call and interpret this tool correctly.

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 description coverage is 100%, so the baseline is 3, but the description adds real meaning: runId comes from enrich_domains run.run_id (or the console URL), offset/limit page rows in write order, and the caller should loop with nextOffset until it is null while finished is true. That paging contract is not derivable from the schema alone.

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?

Starts with a precise verb+resource+scope: 'Read the status and result rows of an enrich_domains run started with waitForFinish=false, one page at a time.' It explicitly distinguishes itself from siblings enrich_domains (starting a run) and normalize_domains (cost preview), so an agent can route without opening another schema.

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?

Has dedicated WHEN TO USE and WHEN NOT TO USE sections: use after enrich_domains returns run.run_id to poll until finished and page rows; do not use to start an enrichment or preview cost, and cannot read runs of other Actors. Both the trigger condition and the exclusions are stated explicitly.

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