Tool reference

All 18 tools, generated from https://api.unzoi.com/mcp/tools.json — the schemas the server actually accepts, not a second copy of them.

Every tool maps onto a REST endpoint, and the arguments are that endpoint's query parameters (for create_watch, the fields of its request body). Two argument shapes are richer than their query-string form, because a model emits them more reliably: facets is an array of strings rather than a comma-separated list, and signals is an array of {name, min, max} objects rather than the packed name:min:max syntax. Every tool declares additionalProperties: false — an argument it does not list is refused — and an outputSchema, the shape of what it returns.

The tools cover searching, expanding, counting over time, resolving names, monitoring and relationships. The relationship tools, related_entities, connection_path, entity_network and shared_exposures, count co-mentions in the reporting and return the articles as evidence; Relationships explains what they measure and what they do not. Every tool result reports credits_charged, what the call was charged; every tool takes estimate to price a call without running it and max_credits to cap it.

search_news

Equivalent to /search over REST.

Search the news index. Returns ranked articles with image, topics, entities, locations, and versioned industry/business/risk language signals. Supports keyword, semantic, or hybrid ranking, exact metadata filters, numeric signal ranges, pagination, and facets. Omit `q` for a newest-first browse of whatever the filters match; pass `story_id` to list every article in one story. Never conclude that something does not exist when `partial` is true, `coverage` is not `complete`, or `from_clamped` is true: retry, narrow the time range, or check `account_status` for the plan's archive depth.

Credits: 1 for keyword ranking or a browse, 2 for semantic, 3 for hybrid; 1-4 with near, bbox, amount_min or amount_max, whose candidates are checked in batches of 500; a cursor page costs 1-2 to start and 1-3 after; +1-2 per entity_id; +1 when signal_percentile_min resolves a threshold; +1 per full 1000 rows of offset. Pass estimate=true to get the exact range without running the call, or max_credits to refuse anything costlier.

Returns {attribution, coverage, credits_charged, facets, from_clamped, has_more, history_days, limit, mode, next_cursor, offset, partial, resolved, results, signal_threshold, total, total_relation} as structuredContent, typed by the tool's outputSchema. An argument not listed above is refused.

list_stories

Equivalent to /stories over REST.

Search and collapse results into deduplicated stories (one real event across many outlets). Returns story_id, article count, outlet count, and a representative headline. Prefer this over search_news whenever the results go into a context window. Never conclude that something does not exist when `partial` is true, `coverage` is not `complete`, or `from_clamped` is true: retry, narrow the time range, or check `account_status` for the plan's archive depth.

Credits: 1, or 2 semantic and 3 hybrid unless sort=recency; +1 with near, bbox, event_type or amount bounds; +1-2 per entity_id; +1 when signal_percentile_min resolves a threshold; +1 per full 100 rows of offset, which stops at 1000. Pass estimate=true to get the exact range without running the call, or max_credits to refuse anything costlier.

Returns {attribution, coverage, credits_charged, from_clamped, has_more, history_days, limit, offset, partial, resolved, signal_threshold, stories, total, total_relation} as structuredContent, typed by the tool's outputSchema. An argument not listed above is refused.

top_headlines

Equivalent to /top-headlines over REST.

Most-recent articles, optionally filtered by indexed article metadata and time range. The same as search_news with no `q`. Never conclude that something does not exist when `partial` is true, `coverage` is not `complete`, or `from_clamped` is true: retry, narrow the time range, or check `account_status` for the plan's archive depth.

Credits: 1; 1-4 with near, bbox, amount_min or amount_max, whose candidates are checked in batches of 500; a cursor page costs 1-2 to start and 1-3 after; +1-2 per entity_id; +1 when signal_percentile_min resolves a threshold; +1 per full 1000 rows of offset. Pass estimate=true to get the exact range without running the call, or max_credits to refuse anything costlier.

Returns {attribution, coverage, credits_charged, facets, from_clamped, has_more, history_days, limit, mode, next_cursor, offset, partial, resolved, results, signal_threshold, total, total_relation} as structuredContent, typed by the tool's outputSchema. An argument not listed above is refused.

get_article

Equivalent to /doc/{id} over REST.

Fetch a single article's rich metadata by id, including names, structured locations and dates, quotations, amounts, related media, links, and alternate URLs. The body is never returned; link the url.

Credits: 1. Pass estimate=true to get the exact range without running the call, or max_credits to refuse anything costlier.

Returns {activity_density, amounts, amp_url, authors, cities, collected_at, countries, credits_charged, date_mentions, event_types, id, image, language, links, location_details, locations, matched_locations, mentioned_dates, mobile_url, names, negative_score, organizations, persons, polarity, positive_score, published_at, publisher_country, quotes, regions, related_images, score, self_reference_density, signals, social_images, social_videos, source, source_type, story_id, title, tone, topics, url, word_count} as structuredContent, typed by the tool's outputSchema. An argument not listed above is refused.

find_related

Equivalent to /similar/{id} over REST.

Find articles semantically similar to a given article id (More-Like-This). Returns distinct related stories (deduplicated across outlets), excluding the seed article. Cheaper and usually better than reformulating a query. Never conclude that something does not exist when `partial` is true, `coverage` is not `complete`, or `from_clamped` is true: retry, narrow the time range, or check `account_status` for the plan's archive depth.

Credits: 2, for the vector search behind it. Pass estimate=true to get the exact range without running the call, or max_credits to refuse anything costlier.

Returns {attribution, coverage, credits_charged, facets, from_clamped, has_more, history_days, limit, mode, next_cursor, offset, partial, resolved, results, signal_threshold, total, total_relation} as structuredContent, typed by the tool's outputSchema. An argument not listed above is refused.

get_story

Equivalent to /stories/{id} over REST.

Expand one story by its story_id (from list_stories or any article): the article and outlet counts, every outlet, when it was first and last seen, the entities and topics it is about, and its newest articles as compact hits. One call, no re-search. `articles_truncated` true means more members exist: page them with search_news and story_id. Never conclude that something does not exist when `partial` is true, `coverage` is not `complete`, or `from_clamped` is true: retry, narrow the time range, or check `account_status` for the plan's archive depth.

Credits: 2 for the whole story, however many articles it lists. Pass estimate=true to get the exact range without running the call, or max_credits to refuse anything costlier.

Returns {articles, articles_returned, articles_truncated, attribution, count, coverage, credits_charged, first_reported, first_seen, from_clamped, history_days, languages, last_seen, outlets, partial, publisher_countries, representative_article_id, sources, sources_by_first_seen, story_id, title, title_variants, top_organizations, top_persons, top_topics, url} as structuredContent, typed by the tool's outputSchema. An argument not listed above is refused.

resolve_entity

Equivalent to /entities over REST.

Find the spellings the index holds for an organization, person, place, topic, author or source, before filtering on it. Filters are exact matches on the index's own values, so `organization=ASML Holding NV` matches nothing while `asml` matches thousands. Returns groups of aliases with a stable entity_id, a canonical spelling, per-alias article counts and a confidence (1.0 exact, 0.8 prefix, 0.6 acronym). Pass a returned `value` verbatim as the matching filter. Ids are deterministic for the resolution version, not a registry. Pass a time range: the values are counted over it. An empty list means the index holds no such spelling in the window, not that the entity is absent from the news. Never conclude that something does not exist when `partial` is true, `coverage` is not `complete`, or `from_clamped` is true: retry, narrow the time range, or check `account_status` for the plan's archive depth.

Credits: 1-2; the second pass runs only when the name's own words match nothing. Pass estimate=true to get the exact range without running the call, or max_credits to refuse anything costlier.

Returns {approximate, attribution, coverage, credits_charged, entities, from_clamped, history_days, limit, partial, q, type} as structuredContent, typed by the tool's outputSchema. An argument not listed above is refused.

aggregate_news

Equivalent to /aggregate over REST.

A time series over the match set: per calendar bucket (hour, day, week, month, or `all` for one bucket), the article count and optionally the distinct story count, the distinct outlet count and a signal's mean and percentiles. One call replaces one search per day. Pass `from`: the plan's archive window fills it in when omitted, and a session without a plan is refused without one. At most 366 buckets. Distinct counts are approximate across indexes and say so. Never conclude that something does not exist when `partial` is true, `coverage` is not `complete`, or `from_clamped` is true: retry, narrow the time range, or check `account_status` for the plan's archive depth.

Credits: 1, whatever the number of buckets; +1 with event_type; +1-2 per entity_id. Pass estimate=true to get the exact range without running the call, or max_credits to refuse anything costlier.

Returns {attribution, buckets, coverage, credits_charged, from, from_clamped, history_days, interval, metrics, partial, resolved, to} as structuredContent, typed by the tool's outputSchema. An argument not listed above is refused.

related_entities

Equivalent to /graph/related over REST.

The entities most often mentioned alongside one entity (organizations, people, places, topics), strongest first, each with its co-mention count and share and, for the strongest, the newest articles mentioning both plus distinct sources, stories and first and last seen. Start from an id resolve_entity returned. Co-mention in reporting is association, not ownership, partnership or causation: read the evidence before stating a relationship, and present it as a reporting pattern. Costs the index queries it issues, reported as credits_charged (at most 16). Never conclude that something does not exist when `partial` is true, `coverage` is not `complete`, or `from_clamped` is true: retry, narrow the time range, or check `account_status` for the plan's archive depth.

Credits: 2 up to 4 + 2 per edge that gets evidence, at most 16; evidence=0 keeps it to 4 or less. Pass estimate=true to get the exact range without running the call, or max_credits to refuse anything costlier.

Returns {attribution, coverage, credits_charged, entity_resolution_version, from_clamped, history_days, indexed_through, note, partial, related, seed} as structuredContent, typed by the tool's outputSchema. An argument not listed above is refused.

connection_path

Equivalent to /graph/path over REST.

How two entities connect in the reporting: the articles mentioning both, and up to five paths through one shared neighbour, each hop with its co-mentions and evidence. Bounded to two hops by design. Co-mention is association, not a real-world relationship. Costs the index queries it issues, reported as credits_charged (at most 16). Never conclude that something does not exist when `partial` is true, `coverage` is not `complete`, or `from_clamped` is true: retry, narrow the time range, or check `account_status` for the plan's archive depth.

Credits: 3-8 with max_hops=1, 3-9 with evidence=0, up to 16 otherwise. Pass estimate=true to get the exact range without running the call, or max_credits to refuse anything costlier.

Returns {attribution, coverage, credits_charged, direct, entity_resolution_version, from, from_clamped, history_days, indexed_through, note, partial, paths, to} as structuredContent, typed by the tool's outputSchema. An argument not listed above is refused.

entity_network

Equivalent to /graph/network over REST.

One entity's neighbours grouped by type for a window. With compare_from or compare_to, what changed against a second window: new and gone neighbours, and ties whose share grew by half or fell by a third. Costs the index queries it issues, reported as credits_charged. Never conclude that something does not exist when `partial` is true, `coverage` is not `complete`, or `from_clamped` is true: retry, narrow the time range, or check `account_status` for the plan's archive depth.

Credits: 2 up to 4 + 2 per edge that gets evidence, at most 16, plus 3 for a comparison window. Pass estimate=true to get the exact range without running the call, or max_credits to refuse anything costlier.

Returns {attribution, changes, coverage, credits_charged, entity_resolution_version, from_clamped, groups, history_days, indexed_through, note, partial, seed} as structuredContent, typed by the tool's outputSchema. An argument not listed above is refused.

shared_exposures

Equivalent to /graph/exposures over REST.

What up to five entities have in common: the articles mentioning all of them, their distinct stories and sources, the facets you ask for (topics, countries, sources and so on), mean and percentile intensities of the signals you name, and the newest shared articles as evidence. Costs the index queries it issues, reported as credits_charged. Never conclude that something does not exist when `partial` is true, `coverage` is not `complete`, or `from_clamped` is true: retry, narrow the time range, or check `account_status` for the plan's archive depth.

Credits: 3, plus 1-2 per entity id, plus 1 with signal_stats. Pass estimate=true to get the exact range without running the call, or max_credits to refuse anything costlier.

Returns {approximate, articles, attribution, coverage, credits_charged, entities, entity_resolution_version, evidence, facets, from_clamped, history_days, indexed_through, note, partial, signals, sources, stories} as structuredContent, typed by the tool's outputSchema. An argument not listed above is refused.

create_watch

Equivalent to POST /watches over REST.

Save a /stories query the index runs for you every interval_minutes, instead of polling. It records an event when a story first reaches minimum_outlets (new_story) or keeps growing (story_growth: crossing 5, 15, 40 or 100 outlets, or 10 more since the last event). Read events with watch_events; with webhook_url each is also POSTed, signed with the webhook_secret returned only here. Each run is charged the credits its query takes, and each webhook delivery attempt 1 credit, to this key; pass estimate=true to see the per-run price before creating it. A run whose answer is partial is asked again rather than skipped. The plan caps how many watches and how short an interval.

Credits: 1 to create. Every run is then charged the credits its query takes, and every webhook delivery attempt costs 1, retries included. Pass estimate=true to get the exact range without running the call, or max_credits to refuse anything costlier.

Returns {consecutive_failures, consecutive_incomplete, created_at, credits_charged, id, interval_minutes, label, last_run_at, minimum_outlets, next_run_at, notify_on, query, status, watermark, webhook_secret, webhook_url} as structuredContent, typed by the tool's outputSchema. An argument not listed above is refused.

list_watches

Equivalent to /watches over REST.

List this account's watches with their status (active, paused_key, paused_credits, failing), last and next run, and the plan's cap.

Credits: 1. Pass estimate=true to get the exact range without running the call, or max_credits to refuse anything costlier.

Returns {count, credits_charged, limit, watches} as structuredContent, typed by the tool's outputSchema. An argument not listed above is refused.

get_watch

Equivalent to /watches/{id} over REST.

Read one watch: the /stories query it runs, its interval and minimum_outlets, which events it records, its webhook_url, and its status (active, paused_key, paused_credits, failing) with the last and next run and the watermark. Check it to learn why a watch is quiet before creating another.

Credits: 1. Pass estimate=true to get the exact range without running the call, or max_credits to refuse anything costlier.

Returns {consecutive_failures, consecutive_incomplete, created_at, credits_charged, id, interval_minutes, label, last_run_at, minimum_outlets, next_run_at, notify_on, query, status, watermark, webhook_url} as structuredContent, typed by the tool's outputSchema. An argument not listed above is refused.

delete_watch

Equivalent to DELETE /watches/{id} over REST.

Delete a watch with its state and its events. Nothing more is recorded or delivered for it, the deleted events cannot be read back, and the plan's watch count drops at once.

Credits: 1. Pass estimate=true to get the exact range without running the call, or max_credits to refuse anything costlier.

Returns {credits_charged, deleted, id} as structuredContent, typed by the tool's outputSchema. An argument not listed above is refused.

watch_events

Equivalent to /watches/{id}/events over REST.

Read a watch's events, newest first: new_story and story_growth, each with the story's counts and, when a webhook is set, its delivery status. Page with after set to the previous response's next_after. Events are kept seven days.

Credits: 1. Pass estimate=true to get the exact range without running the call, or max_credits to refuse anything costlier.

Returns {credits_charged, events, next_after, watch_id} as structuredContent, typed by the tool's outputSchema. An argument not listed above is refused.

account_status

Equivalent to /account over REST.

Report this session's account: plan, credits a minute, the monthly credit allocation and how much of it is used, whether the key stops at its allocation or bills overage, how far back the plan may query (history_days; null = the full archive), calls and credits this session, and whether metered billing is active.

Check it before a large job: it is how to plan credits and a time range instead of discovering the limits by being refused or by getting fewer results than you expected.

Free: 0 credits.

Returns {attribution, calls_this_session, credits_limit, credits_per_minute, credits_remaining, credits_reset_secs, credits_this_session, credits_used, hard_cap, history_days, metered_billing, plan, tenant} or {mode, note} as structuredContent, typed by the tool's outputSchema. An argument not listed above is refused.

Calling one directly

Nothing about this is special — it is JSON-RPC over one POST:

curl -s -X POST https://api.unzoi.com/mcp \
  -H "x-api-key: $UNZOI_KEY" \
  -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_stories",
      "arguments": { "q": "semiconductor export controls", "limit": 5 }
    }
  }'

The result carries the payload twice: as structuredContent, the typed JSON object whose shape is the tool's outputSchema — the OpenAPI response schema, inlined — and as one text content block holding the same JSON for clients that predate structuredContent. Either one is the body GET /stories returns. Read structuredContent if your client exposes it; otherwise parse the text block once. Never both. A host that validates results against outputSchema can: partial and coverage are required on every search-shaped tool. See Transport for the handshake, and Errors for what a refusal looks like.

Arguments are checked

An argument a tool does not declare is refused, as JSON-RPC -32602 with the name you probably meant. It is not dropped. Until September 2026 an unknown argument was silently ignored, which searched everything: a typo in a filter name widened the query instead of failing it.

{
  "jsonrpc": "2.0", "id": 2,
  "error": {
    "code": -32602,
    "message": "Unknown parameter 'langauge'. Did you mean 'language'?",
    "data": { "code": "unknown_parameter" }
  }
}

Three refusals share that shape, told apart by error.data.code:

• unknown_parameter — an argument the tool does not declare.
• unknown_signal — a name in signal or signals that is not one of the published signals. It used to match nothing, which looked like no coverage.
• invalid_parameter — a value outside its enum or range: a view that is not one of full/compact, a facets field the index cannot count, signal_min without signal, a limit above 100.

All three are protocol errors, not tool errors: the call never ran, it cost nothing, and the session is fine. MCP errors has the mapping.

Asking for less

search_news, top_headlines and find_related take view: full (the default) returns the whole Article; compact keeps id, language, published_at, score, source, story_id, title, url — enough for a model to decide what to read next, at a fraction of the tokens. get_story lists its articles that way already; get_article always returns the full record.