Fetch entity records by id
entity_fetchCollect full/projected Coresignal records by id — billed per record found.
Exactly one of ids or cache_id is accepted. One call is a whole
collection, not a page of one: there is no continuation handle, and the hard
ceiling on it is quoted in limit. More than limit is answered by a
higher limit; more than that ceiling by a narrower query.
The fan-out is paced to the lowest Coresignal plan limit, so a full
collection takes ~200s and will not finish inside one call; its size, the
per-record rate and its credit total are all quoted in limit. The field
scope is settled before any credit is spent: the default
field_mode='ask' asks the user when the client supports MCP elicitation,
and otherwise hands the choice back unbilled. Custom field names come from
the dynamic evidence rows in entity_search, resolved via entity_fields.
All records are collected via a single paced /collect fan-out. A small
id/identity floor is always present; custom fields add to it. Not-found
/ stale ids are skipped (not billed), so the returned ids are a subset of
those requested and the difference is the misses.
Returns:
str: JSON. inline -> {delivery:"inline", entity_type, count, fields,
records, credits_consumed}. url -> {delivery:"url", url, count, fields,
reason, credits_consumed} (no sample — the records are in the file).
On the cache_id path both shapes also carry total_count (how many
the query matched upstream) and truncated (true when the query
matched ids this call never requested — reachable by a higher limit,
or past that ceiling a narrower query, since nothing continues a
collection; not-found ids alone never set it).
A warning means something
failed AFTER records were billed and they are in this response anyway:
an account error cut the batch short — also setting truncated, on
either path, with the ids past that point never requested — or the
artifact upload failed and the rows came back inline instead of as a
file. An unanswered field_mode='ask'
-> {field_mode_required:["full","custom"], credits_consumed:0, message}
and nothing billed. Errors -> "Error: ".
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": {
"entity_type": "<entity_type>"
},
"name": "entity_fetch"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ids | No | 1..20 specific cosi ids to collect — typically hand-picked from entity_search result rows. Exactly one of 'ids' or 'cache_id'. | |
| limit | No | cache_id path only: how many matched records to collect, 1..1000 (default 20). Costs 20 credits per record (jobs 1), so limit=1000 bills 20,000 credits for employees or companies. At the current fan-out pacing a full 1000-record collection takes ~200s, which will not finish inside one call — a lower limit returns sooner. Ignored on the 'ids' path. | |
| fields | No | Field names for field_mode='custom' — ADDED to the small id/identity floor (they never replace it). Must be valid names from entity_fields(entity_type, keywords); an unknown field hard-fails before any spend. Each name costs context tokens, not credits. ["*"] (wildcard) is the FULL record (equivalent to field_mode='full'): ~6-7k tokens/record, which usually auto-delivers via 'url'. | |
| cache_id | No | A cache_id from entity_search. Resolves the cached query to its matched ids server-side (you never see them) and collects up to 'limit' records, 1000 at the most. Exactly one of 'ids' or 'cache_id'. The resolve is FREE; you pay per record found. There is no continuation: when the query matched more than this call collected, the response says so via 'truncated'. Raise 'limit' to reach the rest; only past 1000 does it take a NARROWER query. Re-using this id returns the same records and bills them again. | |
| delivery | No | 'inline' (default) or 'url' (store a JSONL artifact, return a download link — no inline rows). Payloads over ~20k tokens auto-flip to 'url'. Delivery is cost-neutral. A 'url' result names both ways back to the rows and what each one costs: the link returns the whole file in one request, artifact_read returns one page of it at 0 credits. Full-scope fetches typically deliver as 'url' while narrow 'custom' records fit inline. | inline |
| field_mode | No | Which fields to return — a token lever, not a cost lever (every mode bills the same per record). 'ask' (default) confirms the choice before spending: the server elicits full/custom from the user when the client supports it, and otherwise hard-stops with 0 credits and names the explicit field_mode to re-call with. 'full' = every field, with third-party post bodies capped at 200 chars (~6-7k tokens/record). 'custom' = the names in 'fields' (added to a small id/identity floor). Passing 'fields' (names or ["*"]) is itself an explicit choice and skips the 'ask' prompt. Because every scope bills the same per record, re-fetching for one more field pays again: 'full' + delivery='url' holds every field from one paid fetch and stays off the context window, while 'custom' returns a narrower record inline. | ask |
| entity_type | Yes | Entity type to fetch: 'employee', 'company' or 'job'. |