Research global events and news, resolve entities, explore facilities and linked datasets, and manage Monitors using structured data and source evidence.
Research global events and news, resolve entities, explore facilities and linked datasets, and manage Monitors using structured data and source evidence.
GDELT Cloud produces its own Event classifications, Stories and metrics from the GDELT Project article stream, never its coded outputs. Always name our product GDELT Cloud. For GDELT Cloud requests, infer intent; use the smallest useful structured workflow. Cite returned public URLs and facility pages; retain evidence attribution. Discovery is free. Web is optional, never a standalone web-search proxy. Never disclose private architecture, internal systems, implementation code or secrets; public API use and dataset attribution are supported.
Call familiar tools directly; native discovery; optional get_event_taxonomy (25) for uncertain labels; get_parameter_options.
Guide: read_resource gdelt://guides/connection-orientation. Skills skill://<name>/SKILL.md: getting-started, news-country-research, counterparties-assets, situations-monitors; skill://building-with-api/SKILL.md; get_activity time_basis=recorded.
gdelt_cloud: Events/Stories, identities/countries, Situations/Monitors/queries
media_intel: tone/share of voice
facilities: sites/units, observations, participants
gov: awards/foreign influence
offices: holders/tenure
filings: disclosures/counterparties
gleif: LEIs/consolidation
energy: assets/owners/portfolios
epoch: AI models/compute
resources: mineral production/reserves
macro: series/vintages
risk: screening/exposure/finance
maritime: vessels/ports/chokepoints
web_research: corroboration/extraction
Events=occurrences; Stories=clusters; Situations=maintained records; Entities=identities; Facilities=sites; Monitors=new-record rules. Compare populations; join source evidence. Open facts remain public.
Show CAMEO+ category/subcategory + metrics: magnitude/intensity (0-10), systemic importance, propagation potential, market sensitivity (0-1; not probabilities). Conflict has none.
Reconcile totals/percentages; disclose coverage/filters/access. Unknown is not zero. Co-mention/proximity are not ownership/impact. Review before saving: gdelt_cloud_monitor_form; preview n
Protocol
Pass100/10016 / 16 pts
Connection, authentication, and protocol compatibility.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description95/100
Change the selected organization Monitors atomically; requires Monitor-management access. enable starts checks, disable pauses them, and delete permanently removes the Monitors and saved runs. The receipt reports requested/unique_ids counts, affected_ids and not_found; verify success before claiming the change completed.
The description explains the capability, when to use it, and what to expect.
Inputs85/100
Input documentation gives an agent enough context to populate the arguments.
monitor_ids
Organization Monitor UUIDs returned by create_monitor or list_monitors; applies the selected action to those saved Monitors. Choices: get_parameter_options('batch_monitors', 'monitor_ids').
Clear enough to supply this argument.
action
Action on the selected saved Monitors: enable starts checks, disable pauses checks, delete permanently removes them.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description98/100
Persist email or signed-webhook delivery settings for an organization Monitor; requires Monitor-management access. Removing the webhook stops that channel. Explicit secret rotation replaces the current signing secret and returns the replacement once; store it securely. Returns the updated Monitor and any one-time webhook_signing_secret.
The description explains the capability, when to use it, and what to expect.
Inputs90/100
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
monitor_id
Organization Monitor UUID returned by create_monitor or list_monitors; select a Monitor in the connected organization. Choices: get_parameter_options('configure_monitor_delivery', 'monitor_id').
Clear enough to supply this argument.
email
Set email delivery without changing it when omitted.
Clear enough to supply this argument.
webhook_url
Set or replace the public HTTPS webhook destination.
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
remove_webhook
Remove webhook delivery. Cannot be combined with webhook_url.
Clear enough to supply this argument.
rotate_secret
Rotate the configured signing secret and return the replacement once.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description79/100
For requested review before saving, open gdelt_cloud_monitor_form and wait for user confirmation; a preview or paused default is not confirmation. Create an organization-shared new-match Monitor over canonical structured Event or Story criteria, or subject_type=query with an allowlisted query_endpoint and descriptor-validated query_params. Resolve candidates using unified_entity_search, explicitly select the identity, then use its stable ID. Scheduled checks consume no Query Units, and signed webhook delivery is available when the caller's plan allows it. ★ An entity subject accepts THREE id-spaces — `e_…` (spine), `wiki:…` (news) and `llm:…` (extracted identity). Pass whichever id the resolver returned and do not hold out for an `e_` one: the news layer a Monitor reads keys on wiki:/llm:, so several of the most-covered organizations (TikTok, Pentagon, Senate, Supreme Court, ICE, North Korea) have no e_ id.★ A `category` subject watches an event TYPE with no geography — pass conflict_categories / conflict_subcategories / cameoplus_domains / cameoplus_subcategories (at least one; the server refuses an empty selection by name) and nothing else. That is the shape for "every Battles event worldwide"; every other subject needs an entity, a facility, a point, a geography, or a search phrase.
The description explains the capability, when to use it, and what to expect.
Inputs94/100
Input documentation gives an agent enough context to populate the arguments.
name
Short name for the Monitor.
Clear enough to supply this argument.
description
Human-readable purpose or instructions associated with the Monitor draft.
Clear enough to supply this argument.
subject_type
What the Monitor watches. Connected subjects follow selected entities or facilities; category subjects watch Event types without geography and require a taxonomy scope. Query subjects use the selected endpoint filters.
Clear enough to supply this argument.
search
Semantic Event/Story content to match. Required for topic Monitors. This is not entity-name resolution; use unified_entity_search first.
Clear enough to supply this argument.
entity_ids
Resolved entity IDs from unified_entity_search. Select the intended candidates and reuse their e_, wiki: or llm: IDs; never pass bare names. Choices: get_parameter_options('create_monitor', 'entity_ids').
Clear enough to supply this argument.
facility_id
Canonical facility identifier returned by facilities_search or unified_entity_search; reuse the selected facility ID. Choices: get_parameter_options('create_monitor', 'facility_id').
Clear enough to supply this argument.
target_type
For connected Monitors: entity or facility. Prefer this subject for company or asset watches.
Latitude in decimal degrees, north-positive, for the place Monitor center; used with longitude.
Clear enough to supply this argument.
longitude
Longitude in decimal degrees, east-positive, for the place Monitor center; used with latitude.
Clear enough to supply this argument.
radius_km
Distance in kilometres around a facility or point target. Omission preserves the REST radius of 25 km; omit for query subjects.
Clear enough to supply this argument.
data
Whether legacy subjects match Events, Stories or both. Omission preserves events_and_stories; omit for query subjects, whose endpoint determines the data.
Clear enough to supply this argument.
cameoplus_domains
Canonical CAMEO+ domains.
Clear enough to supply this argument.
cameoplus_subcategories
CAMEO+ Event codes within the selected cameoplus_domains; use the corresponding parent domains. Choices: get_parameter_options('create_monitor', 'cameoplus_subcategories').
Clear enough to supply this argument.
conflict_categories
Conflict Event types to watch, such as Battles; scope by what happened rather than Story topic.
Clear enough to supply this argument.
conflict_subcategories
Conflict sub-event types within the selected conflict_categories; use the corresponding parent categories. Choices: get_parameter_options('create_monitor', 'conflict_subcategories').
Clear enough to supply this argument.
story_categories
Story-level topics to watch; distinct from the linked Events taxonomy.
Clear enough to supply this argument.
fatalities_only
Restrict compatible conflict Events to records with fatalities.
Clear enough to supply this argument.
cadence
How often the Monitor checks for newly matching records, subject to the connected account entitlement.
Clear enough to supply this argument.
timezone
IANA timezone name used to interpret the daily schedule, such as America/New_York. Choices: get_parameter_options('create_monitor', 'timezone').
Clear enough to supply this argument.
daily_hour
Hour of the daily check in the selected timezone; retained but ignored for hourly cadence.
Clear enough to supply this argument.
email
Send triggered results by email. Supply a webhook destination when email delivery is disabled.
Clear enough to supply this argument.
webhook_url
Optional HTTPS destination for signed webhook delivery (Watch+). Required when email=false.
Clear enough to supply this argument.
query_endpoint
Public read endpoint whose saved filters define a query Monitor; selects the endpoint-specific filter grammar.
Clear enough to supply this argument.
query_params
Saved filters for query_endpoint. Resolve names first and reuse selected IDs. Omit fixed dates and pagination because scheduled execution supplies its own window and page bounds. Choices: get_parameter_options('create_monitor', 'query_params').
Clear enough to supply this argument.
source_request › anyOf › 0 › endpoint
Public read endpoint that produced the original result. Retained as source context; never executed by the schedule.
Clear enough to supply this argument.
source_request › anyOf › 0 › params
Parameters of the original request, including its discovery dates or pagination. Retained for explanation, independently of the scheduled filters.
Clear enough to supply this argument.
enabled
Set false to save paused. Query subjects default to paused when omitted; legacy subjects can start when a running slot exists. Saving and enabling are separate choices.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description86/100
Save a recipe, private by default; REST validates it with the caller's current access. Common fields: title, endpoint_family, params, time_spec; optional display, visibility (private/workspace), pinned. time_spec: mode=none, rolling with days=1-30/timezone=UTC, or fixed with date_start/date_end. Legacy contract_version=1 remains supported. For contract_version=2 choose exactly one: - investigation: {workflow,target:{id,name,reporting?},sections}; endpoint_family=workspace. workflow: company|minerals|compute|ports|energy|places|officials. Company sections: reporting, facilities, filings; asset workflows: reporting, participants, observations; energy/places/officials: reporting. Select at least one. target.reporting is allowed only for energy/places: {lane:events|stories,params:{...}}. Use stable entity/site IDs, keep calendar bounds in time_spec, and use rolling or fixed for investigations. - request: {tool:<registered tool>}, matching endpoint_family and public params. Tools: unified-search, entity-detail, facilities, facilities-detail, facility-relationships, facility-observations, facility-context, stories, events, filings. Detail params include entity_id or facility_id as applicable; params/display limit must be 1-20 when supplied. No arbitrary endpoint URLs or request graphs. No credentials, cursor, offset or stored results. Saving does not schedule a Monitor.
The description explains the capability, when to use it, and what to expect.
Inputs73/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
recipe
Versioned recipe: title, endpoint_family, params, time_spec; optional display, visibility and pinned. v1 saves a query. contract_version=2 requires exactly one typed investigation or registered request; see tool description. No credentials, cursor, offset or stored results. Choices: get_parameter_options('create_saved_query', 'recipe').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description96/100
Create or expand a shared Situation only when explicitly requested. Account access is checked at execution. Call create_situation directly when authorized. Retry with the same idempotency key and body to retrieve the same receipt, including when work is in progress. Never replace an uncertain key to force duplicate work. Existing canonical reuse returns its receipt without repeating work. Returns situation_uid, created/reused and the admission receipt; reuse that identity for subsequent Situation reads.
The description explains the capability, when to use it, and what to expect.
Inputs93/100
Input documentation gives an agent enough context to populate the arguments.
idempotency_key
Generate a stable request key once per authorized Situation creation or expansion, and reuse it unchanged on retries.
Clear enough to supply this argument.
story_id
Served Story seed. Supply this or event_uid. An ambiguous Event requires selecting its supporting Story explicitly. Choices: get_parameter_options('create_situation', 'story_id').
Clear enough to supply this argument.
event_uid
Coded Event UID from search_events; selects Situations with member Stories linked to that Event. Choices: get_parameter_options('create_situation', 'event_uid').
Clear enough to supply this argument.
situation_uid
Optional existing Situation to expand. The seed Story must already belong to it. Choices: get_parameter_options('create_situation', 'situation_uid').
Clear enough to supply this argument.
direction
Which side of the seed/current Situation frontier to expand along admitted temporal connections.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description99/100
Permanently delete one organization Monitor and its saved runs. Use only when the user explicitly asks to delete it. Returns success after deletion; deletion also removes the Monitor saved runs and cannot be undone through this tool.
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
monitor_id
Organization Monitor UUID returned by create_monitor or list_monitors; select a Monitor in the connected organization. Choices: get_parameter_options('delete_monitor', 'monitor_id').
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description98/100
Permanently delete the caller-owned saved recipe identified by query_id, only when explicitly requested. Requires creator access. Returns success after deletion; it does not delete a Monitor or source data.
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
query_id
Caller-owned saved query UUID to permanently delete only when explicitly requested.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description95/100
Send a signed monitor.test sample to GDELT Cloud's temporary first-party receiver, under the connected organization Preview policy and rate limit. Repeated calls send new samples. Creates no saved Monitor, sends no email and accepts no arbitrary receiver URL. Returns demo transport proof: the submitted request, signature verification and receiver response; private receiver capabilities are withheld.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
name
Label included in the signed demonstration webhook sample.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description91/100
Publication/change evidence linked to a selected identity or country. Use for ongoing application Event/Story feeds, collectors and Monitors, including late arrivals, substantive changes and removals. Resolve candidates with unified_entity_search first. Baselines and unchanged reloads are excluded. Use time_basis=recorded explicitly; omission preserves publication-date filters. Before coding durable checkpoints read_resource skill://building-with-api/SKILL.md for fixed UTC intervals, source capability, positive window_complete, exact pagination and transactional processing. Publication and recorded time are separate from Event occurrence; unavailable history is not zero.
The description explains the capability, when to use it, and what to expect.
Inputs89/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
entity
Selected entity ID from /api/v2/search; returns records linked to that identity. Choices: get_parameter_options('get_activity', 'entity').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
target_type
Typed selected root for a shared connected scope: entity or facility. Use with target_ids.
Clear enough to supply this argument.
target_ids
Comma-separated stable IDs for the selected roots (up to 25). Use with target_type; roots are unioned. Choices: get_parameter_options('get_activity', 'target_ids').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
related_scope
direct matches the selected target. connected includes verified controlled subsidiaries for entities, or identified facility owners and authoritative parent paths for facilities.
Clear enough to supply this argument.
country
Known country attribution. Evidence distinguishes location, actor origin, reporting and source association. Choices: get_parameter_options('get_activity', 'country').
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
kind
Published record type to include in activity evidence.
Clear enough to supply this argument.
change
Publication transition. Defaults to all substantive transitions.
Clear enough to supply this argument.
time_basis
Clock for date/hour filters and ordering: published preserves the serving/reference publication time; recorded uses the durable journal commit time and includes late publications when they become available. Omission retains published compatibility. Choose recorded explicitly for ongoing activity Monitors; source dates remain unchanged.
Clear enough to supply this argument.
date_start
First UTC date in the selected time_basis. Defaults to today; future dates are rejected. Neither clock is Event occurrence time.
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
date_end
Last UTC date in the selected time_basis, inclusive. Defaults to date_start and cannot be later than the current UTC day.
Clear enough to supply this argument.
hour
UTC hour selecting a publication bucket. Requires a single date and rejects hours that have not started. The current hour is allowed and describes publications so far; omit for the whole selected day.
Clear enough to supply this argument.
limit
Number of records to return on this page; pagination describes how to continue.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
recorded_start
Inclusive start of API publication time, as an ISO UTC timestamp. Supply both bounds. Includes late arrivals without changing when the event happened. Cannot combine with reporting-date filters.
Clear enough to supply this argument.
recorded_end
Exclusive end of API publication time, as an ISO UTC timestamp. Supply both bounds. Includes late arrivals without changing when the event happened. Cannot combine with reporting-date filters.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description80/100
Canonical country directory (directory=true) includes quiet countries, alphabetical search, geography and paging. basis=reporting counts distinct Events by occurrence date and Stories by reporting date; default publication preserves journal behavior. Hourly filtering is available only for publication. Missing coverage remains unavailable. Returns data country records, optional hourly activity and actor-country edges, plus meta coverage/freshness. Directory mode includes quiet countries; unavailable counts remain null.
The description explains the capability, when to use it, and what to expect.
Inputs91/100
Explain the meaning of this value, not just its name.
country
Known country attribution. Evidence distinguishes location, actor origin, reporting and source association. Choices: get_parameter_options('get_countries', 'country').
Explain the meaning of this value, not just its name.
basis
publication retains the activity journal clock. reporting uses distinct served Events by occurrence date and location country (country_match=location), and Stories by reporting date under every authoritative country association (the Stories summary country_attribution=all mode). Country buckets may overlap for Stories; totals are computed independently. Reporting has day precision and rejects hour.
Clear enough to supply this argument.
include_event_metrics
Include Event metric maxima with tied-country evidence, five AI-coded metric averages with scored Event counts, and per-country readings/linked identity counts. totals.entities_spotted counts distinct served identity/id-space pairs across the entire scoped Event set, never summed over countries; null when unavailable or not requested. Reporting basis only; occurrence-date and location scope. Averages weight each finite scored canonical Event equally, independently of directory pagination. Unrestricted world averages and linked-identity totals include unlocated/global Events; geographic filters use location. Goldstein remains a signed maximum only. No scored observations gives null/count 0; unavailable context remains null.
Clear enough to supply this argument.
include_context
Include dated macro rollups for the selected geography, with same-period coverage and aggregation methods. Requires intelligence entitlement.
Clear enough to supply this argument.
directory
Include every registered country, even those without observed activity. When omitted, returns the activity view rather than the paginated directory.
Clear enough to supply this argument.
q
Country directory name or ISO code search. Requires directory=true.
Clear enough to supply this argument.
region
Registered geographic region whose member countries narrow the country activity or directory view.
Clear enough to supply this argument.
continent
Registered continent whose member countries narrow the country activity or directory view.
Clear enough to supply this argument.
sort
Directory order: most recently seen in reporting/publication activity (default), name alphabetically, events or stories descending with stable name ties. Requires directory=true.
Clear enough to supply this argument.
limit
Number of countries per directory page; applies only with directory=true.
Clear enough to supply this argument.
offset
Number of directory countries to skip; applies only with directory=true.
Clear enough to supply this argument.
time_basis
Clock for date/hour filters and ordering: published preserves the serving/reference publication time; recorded uses the durable journal commit time and includes late publications when they become available. Omission retains published compatibility. Choose recorded explicitly for ongoing activity Monitors; source dates remain unchanged.
Clear enough to supply this argument.
date_start
First UTC date in the selected time_basis. Defaults to today; future dates are rejected. Neither clock is Event occurrence time.
Clear enough to supply this argument.
date_end
Last UTC date in the selected time_basis, inclusive. Defaults to date_start and cannot be later than the current UTC day.
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
hour
UTC hour selecting a publication bucket. Requires a single date and rejects hours that have not started. The current hour is allowed and describes publications so far; omit for the whole selected day.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description71/100
Country activity, dated economy/resource fundamentals, currencies, facilities and people/offices. Retain source, period, units and missing values. Office-holder records are not a distinct-person count; facilities are not units. Returns data country context and meta evidence/coverage; retain reporting basis, source periods, native units and unknown measurements.
The description explains the capability, when to use it, and what to expect.
Inputs93/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
iso3
Country ISO-3 code returned by get_countries, such as TWN. Choices: get_parameter_options('get_country', 'iso3').
Clear enough to supply this argument.
basis
publication retains the activity journal clock. reporting uses distinct served Events by occurrence date and location country (country_match=location), and Stories by reporting date under every authoritative country association (the Stories summary country_attribution=all mode). Country buckets may overlap for Stories; totals are computed independently. Reporting has day precision and rejects hour.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
time_basis
Clock for date/hour filters and ordering: published preserves the serving/reference publication time; recorded uses the durable journal commit time and includes late publications when they become available. Omission retains published compatibility. Choose recorded explicitly for ongoing activity Monitors; source dates remain unchanged.
Clear enough to supply this argument.
date_start
First UTC date in the selected time_basis. Defaults to today; future dates are rejected. Neither clock is Event occurrence time.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
date_end
Last UTC date in the selected time_basis, inclusive. Defaults to date_start and cannot be later than the current UTC day.
Clear enough to supply this argument.
hour
UTC hour selecting a publication bucket. Requires a single date and rejects hours that have not started. The current hour is allowed and describes publications so far; omit for the whole selected day.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description96/100
Read one resolved Entity's public-source record and reporting context. Returns its public GDELT Cloud URL, attributed thumbnail/avatar when available, linked Story/Event references, co-occurrences, timeline, source_mix and map_pins. Set include_registry=true for authorized registry sections and corporate_context; include_tone=true adds measured media tone (-100..100), coverage and by_language. languages scopes the reporting references and tone. The sources map describes access and measured availability: entitled:false with a missing available field means WITHHELD, never 'not tracked'; entitled sources with status:unknown remain unconfirmed. Preserve these distinctions. Co-occurrence is shared reporting, not a personal relationship or proof of action. Cite publisher evidence for underlying claims.
The description explains the capability, when to use it, and what to expect.
Inputs97/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
entity_id
Known v2 Entity id returned by search_entities or an Event/Story entity_refs item. Put the value in `entity_id`; URL entity ids are accepted. Choices: get_parameter_options('get_entity', 'entity_id').
Clear enough to supply this argument.
start_date
Inclusive start date in YYYY-MM-DD for linked Story/Event references. With end_date, defines a window of at most 30 days.
Clear enough to supply this argument.
end_date
Inclusive end date in YYYY-MM-DD for linked Story/Event references. With days only, start_date is computed as the trailing window ending here.
Clear enough to supply this argument.
days
Window size in days. Used only to complete the range when start_date or end_date is omitted.
Clear enough to supply this argument.
limit
Number of linked Story/Event references to include.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
include_images
Retain source article image URLs on returned cards when available.
Clear enough to supply this argument.
include_registry
Include entitled registry and corporate_context sections: recorded parent/child links and separately attributed parent SEC/list counts. Requires registry access; corporate graph requires exposure access.
Clear enough to supply this argument.
include_tone
When true, attach the media-tone timeline + coverage for the entity (mean source tone over the window, -100..100, plus the underlying article/source coverage). Tone is measured only where the entity is actually covered; missing evidence is unavailable, not neutral — absent buckets mean no measured coverage, never a 0 reading.
Clear enough to supply this argument.
languages
ISO source-language filter, e.g. ['ar','zh','en']. Restricts the linked references and (with include_tone) the tone/coverage to articles in those source languages. Omit for all languages. Choices: get_parameter_options('get_entity', 'languages').
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description89/100
Read an entity timeline of cited public-source facts: published offices, list changes, FARA registrations, federal awards and GDELT Cloud Events. Use for source-backed reporting context, not a private personal background check. Read summary.events_in_window and summary.stories_in_window separately; the Event preview is capped at 15 and is not a count. Event items retain event_id, evidence_url and event_date_basis. NULL means we did not look or could not measure, never zero. events_30d is a deprecated alias of events_in_window. as_of filters dates but uses current identity/attribution, so no_lookahead remains false. Subject to connected-account access; publisher assertions remain attributed, not a compliance determination.
The description explains the capability, when to use it, and what to expect.
Inputs91/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
entity
Selected entity for a cited public-source timeline. Accepts a plain name ('Gazprom'), a canonical entity_id ('e_9917c3cd76622ac3'), a 'wiki:' id, or a Wikipedia URL. Resolve ambiguous names with unified_entity_search and confirm the candidate before using its ID; the dossier can resolve names, but an ID makes the selection auditable. Choices: get_parameter_options('get_entity_dossier', 'entity').
Clear enough to supply this argument.
event_days
Trailing calendar window including the end date, in days. `summary.events_in_window` and `summary.stories_in_window` count coded occurrences and coverage Stories separately using the public serving summaries; the Event timeline preview is.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
as_of
Date-filtered dossier: ingredients are filtered to facts dated on or before this date; offices use the office start/end dates the source publishes. Identity and attribution still use current knowledge, so meta.no_lookahead remains false. Absent = current knowledge. A past date needs `can_use_asof`. The three aliases are the spellings `resolveAsOf` honours everywhere else.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description87/100
Fetch one known v2 Event by id for drilldown after search_events or summarize_events; cite its GDELT Cloud Story URL when present.
The description explains the capability, when to use it, and what to expect.
Inputs92/100
Input documentation gives an agent enough context to populate the arguments.
event_id
Known v2 Event id returned by search_events. Put the value in the `event_id` parameter, for example 'conflict_...' or 'cameoplus_...'. Choices: get_parameter_options('get_event', 'event_id').
Clear enough to supply this argument.
include_images
Keep API-enriched top-article sharing images and linked Entity thumbnails when available.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description78/100
Fetch one Monitor's structured subject, trigger, schedule, delivery state, and most recent execution metadata.
The description explains the capability, when to use it, and what to expect.
Inputs93/100
Input documentation gives an agent enough context to populate the arguments.
monitor_id
Organization Monitor UUID returned by create_monitor or list_monitors; select a Monitor in the connected organization. Choices: get_parameter_options('get_monitor', 'monitor_id').
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description95/100
Fetch one saved Monitor run with its structured result rows and summary. Returns monitor and run, including run status, execution totals, retained matched_items sample and coverage. The stored sample is not every counted match; use get_monitor_run_matches to page those matches.
The description explains the capability, when to use it, and what to expect.
Inputs93/100
Input documentation gives an agent enough context to populate the arguments.
monitor_id
Organization Monitor UUID returned by create_monitor or list_monitors; select a Monitor in the connected organization. Choices: get_parameter_options('get_monitor_run', 'monitor_id').
Clear enough to supply this argument.
run_id
Run UUID returned by list_monitor_runs for this Monitor. Choices: get_parameter_options('get_monitor_run', 'run_id').
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description98/100
Page EVERY match a run counted — get_monitor_run returns only the handful of rows a run retains. A run reports an exact result_count and keeps a small sample, and on most runs those are very different numbers, so reach for this whenever the user asks what a Monitor actually found rather than for a headline count. Each row pairs as_triggered — exactly what the email or webhook asserted, frozen at trigger time and never re-derived — with current, the live record, and a status relating the two: unchanged (still served, asserted fields agree), updated (still served, something the notification asserted has changed), superseded (a Story merged away by same-day reconciliation), or gone (no longer resolvable). ★ A superseded Story generally has NO recoverable successor — say it was merged away rather than searching for a replacement, and never present current as null-because-deleted. Omit cursor for the first page, then follow next_cursor until it is null. matched_items_truncated true means the run matched more than it froze; result_count remains the exact total.
The description explains the capability, when to use it, and what to expect.
Inputs96/100
Input documentation gives an agent enough context to populate the arguments.
monitor_id
Organization Monitor UUID returned by create_monitor or list_monitors; select a Monitor in the connected organization. Choices: get_parameter_options('get_monitor_run_matches', 'monitor_id').
Clear enough to supply this argument.
run_id
Run UUID returned by list_monitor_runs for this Monitor. Choices: get_parameter_options('get_monitor_run_matches', 'run_id').
Clear enough to supply this argument.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
limit
How many matches to return per page. The frozen list cannot shift under a cursor, so page boundaries are stable.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
{
"if": {
"required": [
"_mcp_projection"
]
},
"else": {
"type": "object",
"required": [
"success",
"matches",
"next_cursor"
],
"properties": {
"matches": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"kind",
"status",
"as_triggered",
"current"
],
"properties": {
"id": {
"type": "string",
"description": "Event uid or Story cluster id."
},
"kind": {
"enum": [
"event",
"story"
],
"type": "string"
},
"status": {
"enum": [
"unchanged",
"updated",
"superseded",
"gone"
],
"type": "string",
"description": "unchanged: still served and the asserted fields still agree. updated: still served, but a field the notification asserted has changed. superseded: a Story merged away by same-day reconciliation — the successor is generally NOT recoverable, so report the merge rather than looking for one. gone: no longer resolvable on the serving path."
},
"current": {
"type": [
"object",
"null"
],
"description": "The live card, or null when status is superseded or gone."
},
"as_triggered": {
"type": "object",
"properties": {
"date": {
"type": "string"
},
"title": {
"type": "string"
},
"country": {
"type": [
"string",
"null"
]
},
"category": {
"type": [
"string",
"null"
]
}
},
"description": "Exactly what the email or webhook claimed, frozen at trigger time. Never re-derived."
}
}
}
},
"success": {
"type": "boolean"
},
"next_cursor": {
"type": [
"string",
"null"
],
"description": "Pass back as cursor for the next page. Null means the last page."
},
"result_count": {
"type": "integer",
"description": "The exact number of matches the run reported. Stays exact even when the frozen list was capped."
},
"matched_items_truncated": {
"type": "boolean",
"description": "True when the run matched more than it froze, so the pageable list is a prefix of result_count."
}
}
},
"then": {
"type": "object",
"required": [
"_mcp_projection"
],
"properties": {
"matches": {
"type": "array"
},
"success": {
"type": "boolean"
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"result_count": {
"type": "integer"
},
"_mcp_projection": {
"type": "object",
"required": [
"mode"
],
"properties": {
"mode": {
"const": "compact"
},
"truncated": {
"type": "boolean"
}
},
"description": "Explicitly discloses omitted fields or shortened evidence."
},
"matched_items_truncated": {
"type": "boolean"
}
}
},
"type": "object",
"description": "Full preserves the bounded API response. Compact preserves evidence, coverage, filters and pagination with explicit projection disclosure; neither fetches other pages."
}
Original tool metadata
{
"name": "get_monitor_run_matches",
"title": "GDELT Cloud: get monitor run matches",
"description": "Page EVERY match a run counted — get_monitor_run returns only the handful of rows a run retains. A run reports an exact result_count and keeps a small sample, and on most runs those are very different numbers, so reach for this whenever the user asks what a Monitor actually found rather than for a headline count. Each row pairs as_triggered — exactly what the email or webhook asserted, frozen at trigger time and never re-derived — with current, the live record, and a status relating the two: unchanged (still served, asserted fields agree), updated (still served, something the notification asserted has changed), superseded (a Story merged away by same-day reconciliation), or gone (no longer resolvable). ★ A superseded Story generally has NO recoverable successor — say it was merged away rather than searching for a replacement, and never present current as null-because-deleted. Omit cursor for the first page, then follow next_cursor until it is null. matched_items_truncated true means the run matched more than it froze; result_count remains the exact total.",
"inputSchema": {
"type": "object",
"required": [
"monitor_id",
"run_id"
],
"properties": {
"limit": {
"type": "integer",
"default": 100,
"maximum": 500,
"minimum": 1,
"description": "How many matches to return per page. The frozen list cannot shift under a cursor, so page boundaries are stable."
},
"cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page."
},
"run_id": {
"type": "string",
"description": "Run UUID returned by list_monitor_runs for this Monitor. Choices: get_parameter_options('get_monitor_run_matches', 'run_id').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "identifier",
"parameter": "run_id"
}
},
"monitor_id": {
"type": "string",
"description": "Organization Monitor UUID returned by create_monitor or list_monitors; select a Monitor in the connected organization. Choices: get_parameter_options('get_monitor_run_matches', 'monitor_id').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "identifier",
"parameter": "monitor_id"
}
},
"response_mode": {
"enum": [
"compact",
"full"
],
"type": "string",
"default": "compact",
"description": "Compact chat projection or unchanged bounded full API response; neither fetches another page."
}
},
"additionalProperties": false
},
"outputSchema": {
"if": {
"required": [
"_mcp_projection"
]
},
"else": {
"type": "object",
"required": [
"success",
"matches",
"next_cursor"
],
"properties": {
"matches": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"kind",
"status",
"as_triggered",
"current"
],
"properties": {
"id": {
"type": "string",
"description": "Event uid or Story cluster id."
},
"kind": {
"enum": [
"event",
"story"
],
"type": "string"
},
"status": {
"enum": [
"unchanged",
"updated",
"superseded",
"gone"
],
"type": "string",
"description": "unchanged: still served and the asserted fields still agree. updated: still served, but a field the notification asserted has changed. superseded: a Story merged away by same-day reconciliation — the successor is generally NOT recoverable, so report the merge rather than looking for one. gone: no longer resolvable on the serving path."
},
"current": {
"type": [
"object",
"null"
],
"description": "The live card, or null when status is superseded or gone."
},
"as_triggered": {
"type": "object",
"properties": {
"date": {
"type": "string"
},
"title": {
"type": "string"
},
"country": {
"type": [
"string",
"null"
]
},
"category": {
"type": [
"string",
"null"
]
}
},
"description": "Exactly what the email or webhook claimed, frozen at trigger time. Never re-derived."
}
}
}
},
"success": {
"type": "boolean"
},
"next_cursor": {
"type": [
"string",
"null"
],
"description": "Pass back as cursor for the next page. Null means the last page."
},
"result_count": {
"type": "integer",
"description": "The exact number of matches the run reported. Stays exact even when the frozen list was capped."
},
"matched_items_truncated": {
"type": "boolean",
"description": "True when the run matched more than it froze, so the pageable list is a prefix of result_count."
}
}
},
"then": {
"type": "object",
"required": [
"_mcp_projection"
],
"properties": {
"matches": {
"type": "array"
},
"success": {
"type": "boolean"
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"result_count": {
"type": "integer"
},
"_mcp_projection": {
"type": "object",
"required": [
"mode"
],
"properties": {
"mode": {
"const": "compact"
},
"truncated": {
"type": "boolean"
}
},
"description": "Explicitly discloses omitted fields or shortened evidence."
},
"matched_items_truncated": {
"type": "boolean"
}
}
},
"type": "object",
"description": "Full preserves the bounded API response. Compact preserves evidence, coverage, filters and pagination with explicit projection disclosure; neither fetches other pages."
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description77/100
Read the complete versioned recipe and validated reopen URL (Explore for v1, Workspace for v2). Preserves investigation/request metadata; rolling UTC dates refresh now. Does not execute it.
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
query_id
Saved query UUID returned by list_saved_queries or create_saved_query.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description96/100
Connected Story membership, canonical incidents, entity context and chronology for one Situation. Read meta.situation_source: curated is maintained membership; walked is a weaker graph exploration. Read membership basis/reason and caps; chronology is not proof of cause, and a linked entity is not automatically an actor. Member paging does not shrink whole-situation totals. Returns the REST body unchanged, with shared authentication and query quotas. Use for a maintained narrative and retained membership, not an ad hoc grouping of search hits; inspect edition dates and coverage.
The description explains the capability, when to use it, and what to expect.
Inputs95/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
story_id
A situation_uid (sit_…) from search_situations or any member Story id. Story ids may return a walked exploration when no maintained Situation covers them. Choices: get_parameter_options('get_situation', 'story_id').
Clear enough to supply this argument.
edition_id
Retained edition identifier from get_situation_editions. Pins the published snapshot; use it instead of as_of. Choices: get_parameter_options('get_situation', 'edition_id').
Clear enough to supply this argument.
as_of
Latest edition published at or before this UTC ISO timestamp. No reconstruction before retention began.
Clear enough to supply this argument.
date_start
Earliest member date to include. Defaults to seven days before the anchor Story's own date — not to today, because a situation is anchored on a Story, not on the request clock. On a curated Situation it filters the stored membership and `coverage` is re-derived from the members that survived, so the window reported is never wider than the payload.
Clear enough to supply this argument.
date_end
Latest member date to include. Defaults to seven days after the anchor Story's own date. The span may not exceed 30 days when both bounds are sent — the same ceiling the service compares against, not a number typed into a sentence. On a curated Situation, sending neither bound returns the whole stored span; sending one leaves the other side open.
Clear enough to supply this argument.
limit
Number of records to return on this page; pagination describes how to continue.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
offset
Number of records to skip before this page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
depth
Number of adjudicated connection hops from the anchor in a walked Situation. Indirect reachability is not direct comparison with the anchor. Curated membership ignores this value and discloses that in applied_filters.
Clear enough to supply this argument.
max_nodes
Member Story cap for the Situation graph, independent of page size. Read truncated and caps.members; the limit can bound membership totals.
Clear enough to supply this argument.
include
Optional blocks. `edges` returns one undirected row per adjudicated pair across the bounded graph membership, independently of Story pagination (`limit` and `offset`). An edge can reference a Story outside the returned page; fetch the member pages to hydrate those IDs and inspect `caps` and `scopes` for coverage. `/connections` pages membership provenance, not pairwise edges. Edges are omitted by default; `totals.edge_count` reports all pairs in the selected scope even when the returned graph is capped. Choices: get_parameter_options('get_situation', 'include').
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
{
"if": {
"required": [
"_mcp_projection"
]
},
"else": {
"type": "object",
"required": [
"success",
"data"
],
"properties": {
"data": {
"type": "object",
"properties": {
"caps": {
"type": "object",
"description": "Read every cap and truncation flag before claiming completeness."
},
"title": {
"type": "string"
},
"totals": {
"type": "object",
"description": "Whole returned Situation grain, independent of member-page limit."
},
"stories": {
"type": "array",
"description": "Paged members with membership basis, reason, evidence status and chronological route."
},
"entities": {
"type": "array",
"description": "Participant context and Story references, not automatically actor roles."
},
"incidents": {
"type": "array",
"description": "Canonical incidents; never equate this count with Story count."
},
"situation_uid": {
"type": "string"
}
}
},
"meta": {
"type": "object",
"description": "situation_source: curated (maintained membership) or walked (weaker exploration)."
},
"success": {
"type": "boolean"
},
"applied_filters": {
"type": "object"
}
},
"description": "A single Situation record."
},
"then": {
"type": "object",
"required": [
"_mcp_projection"
],
"properties": {
"data": {
"type": "object",
"description": "Compact records retain IDs, returned links, selected images, evidence and metrics where available; unknown values remain unknown."
},
"meta": {
"type": "object",
"description": "situation_source: curated (maintained membership) or walked (weaker exploration)."
},
"success": {
"type": "boolean"
},
"_mcp_projection": {
"type": "object",
"required": [
"mode"
],
"properties": {
"mode": {
"const": "compact"
},
"truncated": {
"type": "boolean"
}
},
"description": "Explicitly discloses omitted fields or shortened evidence."
},
"applied_filters": {
"type": "object"
}
}
},
"type": "object",
"description": "Full preserves the bounded API response. Compact preserves evidence, coverage, filters and pagination with explicit projection disclosure; neither fetches other pages."
}
Original tool metadata
{
"name": "get_situation",
"title": "GDELT Cloud: get situation",
"description": "Connected Story membership, canonical incidents, entity context and chronology for one Situation. Read meta.situation_source: curated is maintained membership; walked is a weaker graph exploration. Read membership basis/reason and caps; chronology is not proof of cause, and a linked entity is not automatically an actor. Member paging does not shrink whole-situation totals. Returns the REST body unchanged, with shared authentication and query quotas. Use for a maintained narrative and retained membership, not an ad hoc grouping of search hits; inspect edition dates and coverage.",
"inputSchema": {
"type": "object",
"required": [
"story_id"
],
"properties": {
"as_of": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Latest edition published at or before this UTC ISO timestamp. No reconstruction before retention began."
},
"depth": {
"type": "integer",
"default": 1,
"maximum": 3,
"minimum": 1,
"description": "Number of adjudicated connection hops from the anchor in a walked Situation. Indirect reachability is not direct comparison with the anchor. Curated membership ignores this value and discloses that in applied_filters."
},
"limit": {
"type": "integer",
"default": 50,
"maximum": 200,
"minimum": 1,
"description": "Number of records to return on this page; pagination describes how to continue."
},
"offset": {
"type": "integer",
"default": 0,
"minimum": 0,
"description": "Number of records to skip before this page."
},
"include": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"const": "edges"
}
},
{
"type": "null"
}
],
"default": null,
"description": "Optional blocks. `edges` returns one undirected row per adjudicated pair across the bounded graph membership, independently of Story pagination (`limit` and `offset`). An edge can reference a Story outside the returned page; fetch the member pages to hydrate those IDs and inspect `caps` and `scopes` for coverage. `/connections` pages membership provenance, not pairwise edges. Edges are omitted by default; `totals.edge_count` reports all pairs in the selected scope even when the returned graph is capped. Choices: get_parameter_options('get_situation', 'include').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "situation_include",
"parameter": "include"
}
},
"date_end": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Latest member date to include. Defaults to seven days after the anchor Story's own date. The span may not exceed 30 days when both bounds are sent — the same ceiling the service compares against, not a number typed into a sentence. On a curated Situation, sending neither bound returns the whole stored span; sending one leaves the other side open."
},
"story_id": {
"type": "string",
"description": "A situation_uid (sit_…) from search_situations or any member Story id. Story ids may return a walked exploration when no maintained Situation covers them. Choices: get_parameter_options('get_situation', 'story_id').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "identifier",
"parameter": "story_id"
}
},
"max_nodes": {
"type": "integer",
"default": 250,
"maximum": 250,
"minimum": 1,
"description": "Member Story cap for the Situation graph, independent of page size. Read truncated and caps.members; the limit can bound membership totals."
},
"date_start": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Earliest member date to include. Defaults to seven days before the anchor Story's own date — not to today, because a situation is anchored on a Story, not on the request clock. On a curated Situation it filters the stored membership and `coverage` is re-derived from the members that survived, so the window reported is never wider than the payload."
},
"edition_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Retained edition identifier from get_situation_editions. Pins the published snapshot; use it instead of as_of. Choices: get_parameter_options('get_situation', 'edition_id').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "identifier",
"parameter": "edition_id"
}
},
"response_mode": {
"enum": [
"compact",
"full"
],
"type": "string",
"default": "compact",
"description": "Compact chat projection or unchanged bounded full API response; neither fetches another page."
}
},
"additionalProperties": false
},
"outputSchema": {
"if": {
"required": [
"_mcp_projection"
]
},
"else": {
"type": "object",
"required": [
"success",
"data"
],
"properties": {
"data": {
"type": "object",
"properties": {
"caps": {
"type": "object",
"description": "Read every cap and truncation flag before claiming completeness."
},
"title": {
"type": "string"
},
"totals": {
"type": "object",
"description": "Whole returned Situation grain, independent of member-page limit."
},
"stories": {
"type": "array",
"description": "Paged members with membership basis, reason, evidence status and chronological route."
},
"entities": {
"type": "array",
"description": "Participant context and Story references, not automatically actor roles."
},
"incidents": {
"type": "array",
"description": "Canonical incidents; never equate this count with Story count."
},
"situation_uid": {
"type": "string"
}
}
},
"meta": {
"type": "object",
"description": "situation_source: curated (maintained membership) or walked (weaker exploration)."
},
"success": {
"type": "boolean"
},
"applied_filters": {
"type": "object"
}
},
"description": "A single Situation record."
},
"then": {
"type": "object",
"required": [
"_mcp_projection"
],
"properties": {
"data": {
"type": "object",
"description": "Compact records retain IDs, returned links, selected images, evidence and metrics where available; unknown values remain unknown."
},
"meta": {
"type": "object",
"description": "situation_source: curated (maintained membership) or walked (weaker exploration)."
},
"success": {
"type": "boolean"
},
"_mcp_projection": {
"type": "object",
"required": [
"mode"
],
"properties": {
"mode": {
"const": "compact"
},
"truncated": {
"type": "boolean"
}
},
"description": "Explicitly discloses omitted fields or shortened evidence."
},
"applied_filters": {
"type": "object"
}
}
},
"type": "object",
"description": "Full preserves the bounded API response. Compact preserves evidence, coverage, filters and pagination with explicit projection disclosure; neither fetches other pages."
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description83/100
Read a retained, edition-bound Situation brief. Returns the saved edition without generating new research.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
story_id
Stored Situation UID or member Story id. Choices: get_parameter_options('get_situation_brief', 'story_id').
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
edition_id
Retained edition identifier from get_situation_editions. Pins the published snapshot; use it instead of as_of. Choices: get_parameter_options('get_situation_brief', 'edition_id').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
as_of
Latest edition published at or before this UTC ISO timestamp. No reconstruction before retention began.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description88/100
Page every stored membership connection with reporting date, first-observed timestamp, relationship and adjudication evidence. Graph samples never limit this list. Keep date bounds and scope_version while paging; restart at offset 0 after a 409 scope change. Returns data admitted connections, scope version and independent pagination. Connection evidence and adjudication provenance qualify each relationship.
The description explains the capability, when to use it, and what to expect.
Inputs86/100
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
edition_id
Retained edition identifier from get_situation_editions. Pins the published snapshot; use it instead of as_of. Choices: get_parameter_options('get_situation_connections', 'edition_id').
Clear enough to supply this argument.
as_of
Latest edition published at or before this UTC ISO timestamp. No reconstruction before retention began.
Clear enough to supply this argument.
scope_version
Optional version from the preceding page scope. A changed scope returns 409 instead of silently mixing pages. Choices: get_parameter_options('get_situation_connections', 'scope_version').
Clear enough to supply this argument.
date_start
Optional earliest member reporting date. Omit both dates for the full servable membership.
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
date_end
Optional latest member reporting date. No implicit first200-member truncation.
Clear enough to supply this argument.
limit
Number of records to return on this page; pagination describes how to continue.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
offset
Number of records to skip before this page.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description93/100
List retained Situation editions. Returns saved editions without generating new research. Returns data retained-edition records with their snapshot identifiers and publication metadata, plus pagination for selecting a frozen edition.
The description explains the capability, when to use it, and what to expect.
Inputs69/100
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
story_id
Stored Situation UID or member Story id. Choices: get_parameter_options('get_situation_editions', 'story_id').
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
limit
Number of records to return on this page; pagination describes how to continue.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
offset
Number of records to skip before this page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description93/100
Read entities mentioned in reporting retained by a stored Situation, with pagination independent of the detail view's entity/member caps. summary covers the whole date scope; pagination.total covers the entity_type filter. Types are observed, not a closed enum. Preserve identity_status, unavailable names, supporting_stories samples and measurement metadata; linked reporting does not establish involvement or exposure. Returns the bounded API receipt under the connected account's access; this does not build private personal profiles.
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
story_id
Stored Situation UID (sit_…) from search_situations. Walked Story neighborhoods are not stored membership and are refused. Choices: get_parameter_options('get_situation_entities', 'story_id').
Clear enough to supply this argument.
edition_id
Retained edition identifier from get_situation_editions. Pins the published snapshot; use it instead of as_of. Choices: get_parameter_options('get_situation_entities', 'edition_id').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
as_of
Latest edition published at or before this UTC ISO timestamp. No reconstruction before retention began.
Clear enough to supply this argument.
scope_version
Optional version from the preceding page scope. A changed scope returns 409 instead of silently mixing pages. Choices: get_parameter_options('get_situation_entities', 'scope_version').
Clear enough to supply this argument.
date_start
Optional earliest member reporting date. Omit both dates for the full servable membership.
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
date_end
Optional latest member reporting date. No implicit first200-member truncation.
Clear enough to supply this argument.
entity_type
Case-insensitive entity kind from summary.by_type. unknown selects untyped records; filtering happens after identity folding.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
limit
Number of records to return on this page; pagination describes how to continue.
Clear enough to supply this argument.
offset
Number of records to skip before this page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description84/100
Independently paginate Situation events. Full-scope summary totals do not depend on this page or graph bounds. Keep the date window unchanged while paging; article totals are member Story sums, not globally unique URLs. Returns data Event cards, full-scope summary, scope version and independent pagination; inspect coverage before treating an empty page as absence.
The description explains the capability, when to use it, and what to expect.
Inputs80/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
story_id
Stored Situation UID (sit_…) from search_situations. Choices: get_parameter_options('get_situation_events', 'story_id').
Clear enough to supply this argument.
edition_id
Retained edition identifier from get_situation_editions. Pins the published snapshot; use it instead of as_of. Choices: get_parameter_options('get_situation_events', 'edition_id').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
as_of
Latest edition published at or before this UTC ISO timestamp. No reconstruction before retention began.
Clear enough to supply this argument.
scope_version
Optional version from the preceding page scope. A changed scope returns 409 instead of silently mixing pages. Choices: get_parameter_options('get_situation_events', 'scope_version').
Clear enough to supply this argument.
date_start
Optional earliest member reporting date. Omit both dates for the full servable membership.
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
date_end
Optional latest member reporting date. No implicit first200-member truncation.
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
limit
Number of records to return on this page; pagination describes how to continue.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
offset
Number of records to skip before this page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
record_ids
Up to eight comma-separated retained Event UIDs. Requires edition_id or as_of, cannot be combined with date_start or date_end, and returns complete frozen records in edition order. Offset and limit paginate that selected set. Choices: get_parameter_options('get_situation_events', 'record_ids').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description78/100
Independently paginate Situation stories. Full-scope summary totals do not depend on this page or graph bounds. Keep the date window unchanged while paging; article totals are member Story sums, not globally unique URLs. Returns data Story cards, full-scope summary, scope version and independent pagination. A bounded page does not establish complete membership coverage.
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
story_id
Stored Situation UID (sit_…) from search_situations. Choices: get_parameter_options('get_situation_stories', 'story_id').
Clear enough to supply this argument.
edition_id
Retained edition identifier from get_situation_editions. Pins the published snapshot; use it instead of as_of. Choices: get_parameter_options('get_situation_stories', 'edition_id').
Clear enough to supply this argument.
as_of
Latest edition published at or before this UTC ISO timestamp. No reconstruction before retention began.
Clear enough to supply this argument.
scope_version
Optional version from the preceding page scope. A changed scope returns 409 instead of silently mixing pages. Choices: get_parameter_options('get_situation_stories', 'scope_version').
Clear enough to supply this argument.
date_start
Optional earliest member reporting date. Omit both dates for the full servable membership.
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
date_end
Optional latest member reporting date. No implicit first200-member truncation.
Clear enough to supply this argument.
limit
Number of records to return on this page; pagination describes how to continue.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
offset
Number of records to skip before this page.
Clear enough to supply this argument.
record_ids
Up to eight comma-separated retained Story IDs. Requires edition_id or as_of, cannot be combined with date_start or date_end, and returns complete frozen records in edition order. Offset and limit paginate that selected set. Choices: get_parameter_options('get_situation_stories', 'record_ids').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description84/100
Fetch one known v2 Story by id with its public GDELT Cloud URL, normalized geo, linked Events/Entities, metrics, and top 3 inline articles.
The description explains the capability, when to use it, and what to expect.
Inputs93/100
Input documentation gives an agent enough context to populate the arguments.
story_id
Known v2 Story id returned by search_stories or linked from an Event. Put the value in the `story_id` parameter; do not use a generic `id` key. Choices: get_parameter_options('get_story', 'story_id').
Clear enough to supply this argument.
include_images
Keep API-enriched top-article sharing images and linked Entity thumbnails when available.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description86/100
Fetch the full paginated source-article list for one Story after get_story or search_stories, including source favicons and article sharing images when available.
The description explains the capability, when to use it, and what to expect.
Inputs73/100
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
story_id
Known v2 Story id. Put the value in `story_id`; use after search_stories/get_story when the top 3 inline articles are not enough. Choices: get_parameter_options('get_story_articles', 'story_id').
Clear enough to supply this argument.
limit
Number of source articles to return from the full paginated article list.
Clear enough to supply this argument.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
include_images
Retain source article image URLs on returned cards when available.
Clear enough to supply this argument.
language
Origin-language filter using ISO language codes. Choices: get_parameter_options('get_story_articles', 'language').
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
publisher_country_iso3
Filter only articles with a known, provenance-backed publisher country. Unknown publishers are never guessed. Choices: get_parameter_options('get_story_articles', 'publisher_country_iso3').
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
date
Single Story partition date used to scope its source articles; distinct from when an article page was published.
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
days
Trailing date window. `window` is an alias.
Explain the meaning of this value, not just its name.
start_date
First Story partition date. `date_start` is an alias.
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
end_date
Last Story partition date. `date_end` is an alias.
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
offset
Legacy number of source-article rows to skip; prefer the continuation cursor for new calls.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description84/100
Atlas geopolitical-risk index at world, continent, region, or country level. `own_coverage` supports the Events and Attention lenses. `world_corpus` is one fixed count-weighted GPR series and requires variant=gpr, metric=gpr, and weighting=attention; it is the reference construction for cross-country time-series work. `geo` is required outside level=world. Official readings below the evidence floor remain null with insufficient_data. Country own_coverage rows may separately return best_effort: an unbanded low-count daily calculation, marked with an asterisk in Atlas. Keep its record count, coder and baseline evidence; it can move sharply on a single record and must not become a confident risk label or trend. Zero coverage, missing or pooled baselines, and open UTC days never get an estimate. Use search_events for the underlying incidents.
The description explains the capability, when to use it, and what to expect.
Inputs84/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
construction
Own-coverage series or the count-weighted world-corpus reference. The world-corpus reference uses the gpr variant/metric and attention weighting.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
level
Spatial aggregation of the risk series: the world or a selected continent, region or country.
Clear enough to supply this argument.
geo
Place appropriate to level, using a country ISO-3 code or a returned region/continent identifier. Omit for the world series. Choices: get_parameter_options('intelligence_gpr', 'geo').
Clear enough to supply this argument.
variant
GPR lens. `lens` is the legacy alias. Defaults to `gpr` for world_corpus and `events` otherwise.
Clear enough to supply this argument.
metric
Measure to read from the returned geopolitical-risk series; select it for the chosen construction and variant.
Explain the meaning of this value, not just its name.
weighting
How country observations contribute to the regional or world aggregate; attention weights by coverage, equal gives countries equal weight.
Resolve the mismatch between this description and its schema constraints.
component
Component of the selected risk variant used for decomposition; use get_parameter_options with the variant to discover compatible components. Choices: get_parameter_options('intelligence_gpr', 'component').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
date
A single day (YYYY-MM-DD) instead of a range.
Clear enough to supply this argument.
date_start
Inclusive window start (YYYY-MM-DD).
Clear enough to supply this argument.
date_end
Inclusive window end (YYYY-MM-DD).
Clear enough to supply this argument.
window
Length of the trailing display window in days. Defaults to 7 only when no explicit dates are supplied; omit when sending date_start/date_end.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
as_of
Observation vintage cutoff. Frozen normalization is the currently available reference; this is not a fully point-in-time backtest of the baseline.
Clear enough to supply this argument.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
limit
Number of records to return on this page; pagination describes how to continue.
Clear enough to supply this argument.
offset
Number of records to skip before this page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
Shorten the title to an action and subject; move usage details into the description.
Description85/100
Read a place’s 0–100 condition with dynamic Event and annual structural axes. A best_effort structural-only score describes annual WDI/WGI/V-Dem indicators, not current reporting. Retain axis_basis, indicator count, reference_year and evidence_note. Missing measurements are unknown, never zero. as_of constrains dynamic observations but is not a historical snapshot of annual inputs or normalization. Returns structural and dynamic axes, their evidence basis/reference years, geographic rollups and limitations. Use the returned coverage before comparing scores.
The description explains the capability, when to use it, and what to expect.
Inputs83/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
country
Country ISO3 shortcut. Takes precedence over geo. Choices: get_parameter_options('intelligence_posture', 'country').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
level
Spatial aggregation of the structural and dynamic posture evidence.
Clear enough to supply this argument.
geo
Place appropriate to level, using a country ISO-3 code or a returned region/continent name. For level=world, omit geo; a supplied country selects the country view. Choices: get_parameter_options('intelligence_posture', 'geo').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
scope
Dynamic evidence scope to include in posture calculations. Omission includes all scopes.
Clear enough to supply this argument.
window
Duration of the dynamic Event window.
Clear enough to supply this argument.
weighting
How country observations contribute to the geographic rollup; a country view is not an aggregate and the response discloses fallback behavior.
Clear enough to supply this argument.
date
Window end date. Omission uses the latest computed observations.
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
as_of
Observation vintage cutoff. Structural inputs and normalization are not a historical snapshot; inspect response limitations.
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description95/100
List valid admin1 values for exactly one country so users can safely drill into state/province-level location filters. Returns data state/province options with names and observed activity, plus the resolved country/window; use the returned names for admin1 filters.
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
country
One plain English country name, such as 'France' or 'United States'. ISO-3 and legacy FIPS aliases are accepted, but the response is country-scoped and never returns the full ADM1 catalog. Choices: get_parameter_options('list_admin1', 'country').
Clear enough to supply this argument.
date
Anchor date for the window. Alone it selects that single day; combined with `days` it ends the trailing span on that date.
Clear enough to supply this argument.
date_start
First day of an explicit window. May not be combined with `days`/`window`.
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
date_end
Last day of an explicit window. May not be combined with `days`/`window`.
Clear enough to supply this argument.
days
Trailing window in days the region counts are measured over, ending today unless `date` moves the anchor. Both `7` and `7d` are accepted. The window actually used is echoed as `window_days` and in `applied_filters`.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
{
"if": {
"required": [
"_mcp_projection"
]
},
"else": {
"type": "object",
"properties": {
"admin1": {
"type": "array",
"items": {
"type": "string"
},
"description": "Accepted state/province labels for location filtering; empty means no labels returned for this scope."
},
"source": {
"type": [
"string",
"null"
],
"description": "Vocabulary source when disclosed; null means it was not supplied."
},
"country": {
"type": "string",
"description": "Selected country whose location vocabulary is listed."
},
"success": {
"type": "boolean",
"description": "The lookup completed."
}
},
"description": "Valid admin1 (state/province) values for exactly one country."
},
"then": {
"type": "object",
"required": [
"_mcp_projection"
],
"properties": {
"admin1": {
"type": "array"
},
"source": {
"type": [
"string",
"null"
]
},
"country": {
"type": "string"
},
"success": {
"type": "boolean",
"description": "The lookup completed."
},
"_mcp_projection": {
"type": "object",
"required": [
"mode"
],
"properties": {
"mode": {
"const": "compact"
},
"truncated": {
"type": "boolean"
}
},
"description": "Explicitly discloses omitted fields or shortened evidence."
}
}
},
"type": "object",
"description": "Full preserves the bounded API response. Compact preserves evidence, coverage, filters and pagination with explicit projection disclosure; neither fetches other pages."
}
Original tool metadata
{
"name": "list_admin1",
"title": "List states and provinces",
"description": "List valid admin1 values for exactly one country so users can safely drill into state/province-level location filters. Returns data state/province options with names and observed activity, plus the resolved country/window; use the returned names for admin1 filters.",
"inputSchema": {
"type": "object",
"required": [
"country"
],
"properties": {
"date": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Anchor date for the window. Alone it selects that single day; combined with `days` it ends the trailing span on that date."
},
"days": {
"anyOf": [
{
"type": "integer",
"maximum": 30,
"minimum": 1
},
{
"type": "null"
}
],
"default": null,
"description": "Trailing window in days the region counts are measured over, ending today unless `date` moves the anchor. Both `7` and `7d` are accepted. The window actually used is echoed as `window_days` and in `applied_filters`."
},
"country": {
"type": "string",
"description": "One plain English country name, such as 'France' or 'United States'. ISO-3 and legacy FIPS aliases are accepted, but the response is country-scoped and never returns the full ADM1 catalog. Choices: get_parameter_options('list_admin1', 'country').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "identifier",
"enum_id": "country",
"parameter": "country"
}
},
"date_end": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Last day of an explicit window. May not be combined with `days`/`window`."
},
"date_start": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "First day of an explicit window. May not be combined with `days`/`window`."
},
"response_mode": {
"enum": [
"compact",
"full"
],
"type": "string",
"default": "compact",
"description": "Compact chat projection or unchanged bounded full API response; neither fetches another page."
}
},
"additionalProperties": false
},
"outputSchema": {
"if": {
"required": [
"_mcp_projection"
]
},
"else": {
"type": "object",
"properties": {
"admin1": {
"type": "array",
"items": {
"type": "string"
},
"description": "Accepted state/province labels for location filtering; empty means no labels returned for this scope."
},
"source": {
"type": [
"string",
"null"
],
"description": "Vocabulary source when disclosed; null means it was not supplied."
},
"country": {
"type": "string",
"description": "Selected country whose location vocabulary is listed."
},
"success": {
"type": "boolean",
"description": "The lookup completed."
}
},
"description": "Valid admin1 (state/province) values for exactly one country."
},
"then": {
"type": "object",
"required": [
"_mcp_projection"
],
"properties": {
"admin1": {
"type": "array"
},
"source": {
"type": [
"string",
"null"
]
},
"country": {
"type": "string"
},
"success": {
"type": "boolean",
"description": "The lookup completed."
},
"_mcp_projection": {
"type": "object",
"required": [
"mode"
],
"properties": {
"mode": {
"const": "compact"
},
"truncated": {
"type": "boolean"
}
},
"description": "Explicitly discloses omitted fields or shortened evidence."
}
}
},
"type": "object",
"description": "Full preserves the bounded API response. Compact preserves evidence, coverage, filters and pagination with explicit projection disclosure; neither fetches other pages."
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description80/100
List recent saved runs for one Monitor so an agent can inspect what matched and when delivery occurred.
The description explains the capability, when to use it, and what to expect.
Inputs87/100
Input documentation gives an agent enough context to populate the arguments.
monitor_id
Organization Monitor UUID returned by create_monitor or list_monitors; select a Monitor in the connected organization. Choices: get_parameter_options('list_monitor_runs', 'monitor_id').
Clear enough to supply this argument.
limit
Maximum saved Monitor runs to return.
Clear enough to supply this argument.
offset
Number of records to skip before this page.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description85/100
List visible private/workspace recipes, preserving contract_version and v2 investigation/request metadata. Does not execute them. Returns data visible recipes and meta actor/limit information. Each recipe retains its version, sharing scope and saved query or investigation fields.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description94/100
Read-only match query. For an editable draft, setup or review before saving, call gdelt_cloud_monitor_form instead; it provides country/category choices and email/webhook controls. Preview never saves or sends. Run the same canonical Monitor specification on demand without creating it or consuming a Monitor slot. This metered read sends no email or webhooks. Resolve entity names with unified_entity_search first. Use subject_type=query, query_endpoint and query_params to preserve a public request. New committed records are matched after the prior successful checkpoint. history_days is 7 by default or 30 for setup history; it does not change scheduled matching or first enablement. Preview receipts retain their history dates and basis. Scheduled query runs use an independent committed-publication interval. ★ A `category` subject watches an event TYPE with no geography — pass conflict_categories / conflict_subcategories / cameoplus_domains / cameoplus_subcategories (at least one; the server refuses an empty selection by name) and nothing else. That is the shape for "every Battles event worldwide"; every other subject needs an entity, a facility, a point, a geography, or a search phrase.
The description explains the capability, when to use it, and what to expect.
Inputs96/100
Resolve the mismatch between this description and its schema constraints.
name
Short name for the Monitor being previewed.
Clear enough to supply this argument.
description
Human-readable purpose or instructions associated with the Monitor draft.
Clear enough to supply this argument.
subject_type
What the Monitor watches. Connected subjects follow selected entities or facilities; category subjects watch Event types without geography and require a taxonomy scope. Query subjects use the selected endpoint filters.
Clear enough to supply this argument.
search
Semantic Event/Story content to match. Required for topic Monitors. This is not entity-name resolution; use unified_entity_search first.
Resolve the mismatch between this description and its schema constraints.
entity_ids
Resolved entity IDs from unified_entity_search. Select the intended candidates and reuse their e_, wiki: or llm: IDs; never pass bare names. Choices: get_parameter_options('preview_monitor', 'entity_ids').
Clear enough to supply this argument.
facility_id
Canonical facility identifier returned by facilities_search or unified_entity_search; reuse the selected facility ID. Choices: get_parameter_options('preview_monitor', 'facility_id').
Clear enough to supply this argument.
target_type
For connected Monitors: entity or facility. Prefer this subject for company or asset watches.
Latitude in decimal degrees, north-positive, for the place Monitor center; used with longitude.
Clear enough to supply this argument.
longitude
Longitude in decimal degrees, east-positive, for the place Monitor center; used with latitude.
Clear enough to supply this argument.
radius_km
Distance in kilometres around a facility or point target. Omission preserves the REST radius of 25 km; omit for query subjects.
Clear enough to supply this argument.
data
Whether legacy subjects match Events, Stories or both. Omission preserves events_and_stories; omit for query subjects, whose endpoint determines the data.
Clear enough to supply this argument.
cameoplus_domains
Canonical CAMEO+ domains.
Clear enough to supply this argument.
cameoplus_subcategories
CAMEO+ Event codes within the selected cameoplus_domains; use the corresponding parent domains. Choices: get_parameter_options('preview_monitor', 'cameoplus_subcategories').
Clear enough to supply this argument.
conflict_categories
Conflict Event types to watch, such as Battles; scope by what happened rather than Story topic.
Clear enough to supply this argument.
conflict_subcategories
Conflict sub-event types within the selected conflict_categories; use the corresponding parent categories. Choices: get_parameter_options('preview_monitor', 'conflict_subcategories').
Clear enough to supply this argument.
story_categories
Story-level topics to watch; distinct from the linked Events taxonomy.
Clear enough to supply this argument.
fatalities_only
Restrict compatible conflict Events to records with fatalities.
Clear enough to supply this argument.
cadence
How often the Monitor checks for newly matching records, subject to the connected account entitlement.
Clear enough to supply this argument.
timezone
IANA timezone name used to interpret the daily schedule, such as America/New_York. Choices: get_parameter_options('preview_monitor', 'timezone').
Clear enough to supply this argument.
daily_hour
Hour of the daily check in the selected timezone; retained but ignored for hourly cadence.
Clear enough to supply this argument.
email
Retained email-delivery setting for the draft. Preview never sends email and needs no delivery channel.
Clear enough to supply this argument.
webhook_url
Draft webhook destination. Preview retains it but never contacts it and does not require it.
Clear enough to supply this argument.
query_endpoint
Public read endpoint whose saved filters define a query Monitor; selects the endpoint-specific filter grammar.
Clear enough to supply this argument.
query_params
Saved filters for query_endpoint. Resolve names first and reuse selected IDs. Omit fixed dates and pagination because scheduled execution supplies its own window and page bounds. Choices: get_parameter_options('preview_monitor', 'query_params').
Clear enough to supply this argument.
source_request › anyOf › 0 › endpoint
Public read endpoint that produced the original result. Retained as source context; never executed by the schedule.
Clear enough to supply this argument.
source_request › anyOf › 0 › params
Parameters of the original request, including its discovery dates or pagination. Retained for explanation, independently of the scheduled filters.
Clear enough to supply this argument.
monitor_id
Organization Monitor UUID returned by create_monitor or list_monitors; select a Monitor in the connected organization. Choices: get_parameter_options('preview_monitor', 'monitor_id').
Clear enough to supply this argument.
history_days
Setup history: 7 days by default, or 30. Preview never establishes a scheduled checkpoint or sends delivery; incomplete history remains explicit.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description98/100
Execute a saved Monitor immediately and retain the result for seven days. Sends no notifications and changes neither seen-state nor schedule. Returns the stored run receipt with counts, bounded matched_items and coverage; use run identifiers for later inspection rather than assuming the sample is complete.
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
monitor_id
Organization Monitor UUID returned by create_monitor or list_monitors; select a Monitor in the connected organization. Choices: get_parameter_options('run_monitor_now', 'monitor_id').
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description85/100
Discover actors appearing in reporting within date, geography, type or category filters; use for 'who appears in this reporting?' and co-occurrence/coverage questions. The window defaults to the last 30 DAYS; quiet does not mean unknown identity. For initial identity lookup use unified_entity_search with country_match=strict, inspect candidates, select the intended identity, then reuse its exact ID in the relevant endpoint. Coverage metrics describe the requested window; zero means no coverage in this window; null or failed coverage means unknown. Public reporting mentions and shared Stories do not establish interaction, involvement or misconduct. Never choose an ambiguous top hit silently.
The description explains the capability, when to use it, and what to expect.
Inputs92/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
search
Free-text search across entity name and Wikipedia URL. Exact-name matches are ranked first via match_score before the standard sort, so `search='Nvidia'` surfaces the Nvidia entity when present in the window. Pass the entity name here — this is the param, not `name`.
Clear enough to supply this argument.
type
Kind of entity appearing in the selected reporting; this is identity classification, not an asserted Event actor role. Choices: get_parameter_options('search_entities', 'type').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
start_date
Inclusive start date in YYYY-MM-DD. With end_date, defines an explicit MCP Entity discovery window of at most 30 days.
Clear enough to supply this argument.
end_date
Inclusive end date in YYYY-MM-DD. With days only, start_date is computed as the trailing window ending here. Defaults to today UTC.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
days
Calendar-date window ending today, in days (max 30). `window=7d` and `days=7` are equivalent. When omitted, entity coverage uses the last 30 calendar days with an observed-time bound over the same span. There is no equivalent numeric default: sending days explicitly selects calendar dates and removes the implicit observed-time bound. Pass `days` explicitly, or `date_start`/`date_end`, whenever the window matters.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
event_family
Deprecated legacy linked-evidence filter. Prefer category/categories, which imply Conflict vs CAMEO+. Still accepted for backwards compatibility.
Clear enough to supply this argument.
category
Linked Event top-level category: a Conflict event_type such as 'Battles' or one CAMEO+ domain such as 'INFRASTRUCTURE'. Filters Entities by linked Story/Event evidence. Choices: get_parameter_options('search_entities', 'category').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
categories
Optional multi-select version of category. Values are OR'd together and sent to the API as category=Battles,CRIME. Choices: get_parameter_options('search_entities', 'categories').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
subcategory
Linked Event subcategory string validated at runtime. Requires category/categories and filters Entities by linked Story/Event evidence. For CAMEO+ categories, prefer stable event codes such as TE01 or IN03; codebook labels are accepted as legacy aliases. Choices: get_parameter_options('search_entities', 'subcategory').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
domain
Deprecated legacy linked CAMEO+ domain filter. Prefer category for new integrations; for DEMOGRAPHIC use category='DEMOGRAPHIC'.
Clear enough to supply this argument.
has_fatalities
Set true to return Entities linked to fatal Events or Stories with fatal linked Events.
Clear enough to supply this argument.
civilian_targeting
Set true to return Entities linked to Conflict Event/Story evidence where ACLED civilian_targeting is populated.
Clear enough to supply this argument.
sort
'significance' ranks by mention/article weight; 'recent' ranks by latest linked Story/Event evidence.
Clear enough to supply this argument.
limit
Number of Entity cards to return.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
include_images
Retain source article image URLs on returned cards when available.
Clear enough to supply this argument.
recorded_start
Inclusive start of API publication time, as an ISO UTC timestamp. Supply both bounds. Includes late arrivals without changing when the event happened. Cannot combine with reporting-date filters.
Clear enough to supply this argument.
recorded_end
Exclusive end of API publication time, as an ISO UTC timestamp. Supply both bounds. Includes late arrivals without changing when the event happened. Cannot combine with reporting-date filters.
Clear enough to supply this argument.
co_occurring_with
Return the entities that appear ALONGSIDE this one — the entities linked to the same Stories, over the same window, narrowed by every other filter on this endpoint. Accepts a spine id (`e_…`), a news id (`wiki:…`) or a name, resolved through the same arbiter as `entity=` on `/api/v2/events` and `/api/v2/stories`, so one handle means the same entity everywhere. The subject is never returned in its own results. Co-occurrence is measured over SHARED STORIES — appearing in the same coverage, which is not a claim that the two entities interacted. A handle that resolves to nothing returns an EMPTY list with a `linkage` reason in `applied_filters`, never the global top entities. Choices: get_parameter_options('search_entities', 'co_occurring_with').
Clear enough to supply this argument.
continent
Continent expanded to its member ISO-3 countries; applied through the same country matching rules.
Clear enough to supply this argument.
country
Country filter. Accepts ISO-3, ISO-2, FIPS or an English name; comma-separate for OR. Matches the event's own location OR either actor's origin country by default, so a result can include events that happened elsewhere — set `country_match` to narrow it to location only. The definition in force is echoed as `applied_filters.country_match`. Choices: get_parameter_options('search_entities', 'country').
Clear enough to supply this argument.
country_match
Which definition of "in this country" the `country` / `region` / `continent` filters use. Applies to `region` and `continent` too, since both expand into the same country set. Note that `group_by=country` buckets on the event's own location, while the default match also admits actor origin — so a filtered total and the bucket for that same country can differ. Pass `country_match=location` when you need the two to agree.
Clear enough to supply this argument.
languages
ISO source-language filter. Restricts coverage metrics to articles in those languages. Choices: get_parameter_options('search_entities', 'languages').
Clear enough to supply this argument.
region
Geographic region expanded to its member ISO-3 countries; applied through the same country matching rules.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description96/100
Retrieve a bounded evidence sample. For counts, trends or "what changed", call summarize_events first for each period with identical structured filters, then sample relevant Events. Displayed pages cannot establish totals or mean metrics. Territorial scope uses country_match=location. Continuous events coverage begins 2026-03-01. Use consecutive windows of at most 30 inclusive days; a calendar month can be too long. Finish pagination.next_cursor within each fixed window before starting the next chunk without a cursor. Without an explicit window, entity filters default to 30 days and other queries to the last 24 hours. meta.query_window reports the effective predicates; meta.coverage describes the available corpus. Retrieve GDELT Cloud's self-produced coded reported Events as supporting evidence: incidents, conflict, diplomacy and economic/energy developments. Classification and temporal order do not prove causation or operational impact. Supports Conflict and CAMEO+ Events, plain-English geography whose region/continent filters expand to country lists, optional admin1 drilldown, categories/subcategories, true embedding semantic search, fatality/civilian-targeting filtering, canonical metric min/max filters, and significance or recent sorting. Returns clean Event cards with geo, actors, Goldstein/severity and CAMEO+ metrics, linked Stories/Entities, GDELT Cloud Story URLs for citation, top 3 articles, source favicons, article sharing images, and linked Entity thumbnails. Entity matching uses coverage through linked Stories; a mention does not establish that the entity is a party to the Event. For ongoing collectors and company watches, discover get_activity (recorded time) and read_resource skill://building-with-api/SKILL.md before coding checkpoints; occurrence-date searches are not an arrival feed. Use for classified evidence and the four CAMEO+ metrics after a population summary; a result page cannot establish population averages.
The description explains the capability, when to use it, and what to expect.
Inputs86/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
start_date
Inclusive YYYY-MM-DD start; at most 30 days with end_date. With days only, computes end_date.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
end_date
Inclusive YYYY-MM-DD end, default today UTC. With days only, computes the trailing start.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
days
Window days. Omit for the REST default: 30 days with entity, rolling past 24 hours otherwise. Set only to deliberately change that window.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
country
One or more plain-English country names or ISO-3 codes (legacy FIPS accepted). OR across Event location and actor origins; pass a list. Choices: get_parameter_options('search_events', 'country').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
source_actor_country
Acting-side origin countries (names or ISO-3). Pair with target_actor_country for direction. Conflict primary actor need not be the initiator. Choices: get_parameter_options('search_events', 'source_actor_country').
Clear enough to supply this argument.
target_actor_country
Receiving-side origin countries (names or ISO-3). Pair with source_actor_country to preserve direction. Choices: get_parameter_options('search_events', 'target_actor_country').
Clear enough to supply this argument.
actor_country
Either actor-origin country, ignoring direction; excludes matches based only on Event location. Choices: get_parameter_options('search_events', 'actor_country').
Clear enough to supply this argument.
region
Plain-English region, expanded to its ISO-3 country list. OR across Event location and actor-origin countries.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
continent
Plain-English continent, expanded to ISO-3 countries; same matching semantics as country.
Clear enough to supply this argument.
admin1
Optional state/province/admin1 name discovered with list_admin1. Filters Event location only, not actor origin. Choices: get_parameter_options('search_events', 'admin1').
Clear enough to supply this argument.
bbox
Geographic bounding box 'lat_min,lon_min,lat_max,lon_max'. Monitor replay requests may supply this exact filter.
Clear enough to supply this argument.
near
Point filter 'latitude,longitude'. Pair with radius_km. Monitor place/facility replay requests supply these exact values.
Clear enough to supply this argument.
radius_km
Distance in kilometres from the selected point for geographic proximity matching.
Clear enough to supply this argument.
languages
Source-language ISO codes, e.g. [ar, zh, en]. Omit for all languages. Choices: get_parameter_options('search_events', 'languages').
Clear enough to supply this argument.
entity
Resolved terminal entity id, news id, or name. Uses the same shared resolver as Stories and entity products. Choices: get_parameter_options('search_events', 'entity').
Clear enough to supply this argument.
entity_match
Coverage through a linked Story, not proof of participation in the Event. Omit to inherit REST defaults.
Clear enough to supply this argument.
office
Office ID from offices_search. Matches published holders during the reporting window or office_as_of; unioned with entity. Refuses >1,000 holders; applied_filters.office_holders discloses unresolved identities. Choices: get_parameter_options('search_events', 'office').
Clear enough to supply this argument.
office_as_of
Valid-time YYYY-MM-DD for office holders. Separate from reporting/replay dates. Missing term evidence is excluded.
Clear enough to supply this argument.
event_family
Deprecated legacy filter. Prefer category/categories, which imply Conflict vs CAMEO+. Still accepted for backwards compatibility.
Clear enough to supply this argument.
category
One category string, e.g. Battles or INFRASTRUCTURE. Use categories for multiple choices. Choices: get_parameter_options('search_events', 'category').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
categories
JSON array (OR combined), e.g. ["INFRASTRUCTURE", "ECONOMIC"], not a JSON-encoded string. Choices: get_parameter_options('search_events', 'categories').
Clear enough to supply this argument.
subcategory
Runtime-validated within category/categories. Conflict labels or CAMEO+ stable codes; codebook labels accepted as aliases. Choices: get_parameter_options('search_events', 'subcategory').
Clear enough to supply this argument.
domain
Deprecated legacy CAMEO+ domain filter. Prefer category/categories for new integrations.
Clear enough to supply this argument.
search
Search text. With search_mode=lexical this is a literal phrase in served Events title/summary or Stories title. By default the complete phrase is checked against name/title evidence and is also embedded for vector ranking; literal matches rank first and remaining results are conceptual neighbours. There is no boolean parser: a query shaped `a OR b` is reduced to its first term and the response says so. Costs an embedding call and can return 503 SEMANTIC_SEARCH_UNAVAILABLE.
Clear enough to supply this argument.
search_mode
Search interpretation. semantic is a bounded hybrid search: complete-phrase name/title matches rank ahead of vector-ranked conceptual neighbours. lexical filters the complete serving set for a case-insensitive literal phrase in Events title/summary or Stories title before pagination; no stemming or boolean parsing. Lexical mode requires a supported serving snapshot and never falls back to the warehouse.
Clear enough to supply this argument.
country_match
Which definition of "in this country" the `country` / `region` / `continent` filters use. Applies to `region` and `continent` too, since both expand into the same country set. Note that `group_by=country` buckets on the event's own location, while the default match also admits actor origin — so a filtered total and the bucket for that same country can differ. Pass `country_match=location` when you need the two to agree.
Clear enough to supply this argument.
has_fatalities
Set true for fatality monitoring. This is the only public fatality filter; there are no fatality min/max params.
Clear enough to supply this argument.
civilian_targeting
Set true for Conflict Events where ACLED civilian_targeting is populated; set false to exclude civilian-targeting Conflict Events.
Clear enough to supply this argument.
significance_min
Lower bound on canonical Event importance across coding families.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
significance_max
Upper bound on canonical Event importance across coding families.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
confidence_min
Lower bound on Event coding confidence. This is the public replacement for the legacy min_confidence API parameter; it does not estimate the probability of a real-world outcome.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
confidence_max
Upper bound on coding confidence rather than a probability of the real-world outcome.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
goldstein_scale_min
Lower bound on signed conflict/cooperation score; negative values describe conflictual actions, positive values cooperation; meaningful for Conflict and CAMEO+ POLITICAL.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
goldstein_scale_max
Upper bound on signed conflict/cooperation score; negative values describe conflictual actions, positive values cooperation; meaningful for Conflict and CAMEO+ POLITICAL.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
magnitude_min
Lower bound on CAMEO+ scale of the change or action. This selects Events with that CAMEO+ measurement.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
magnitude_max
Upper bound on CAMEO+ scale of the change or action. This selects Events with that CAMEO+ measurement.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
systemic_importance_min
Lower bound on CAMEO+ importance of the affected system. This selects Events with that CAMEO+ measurement.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
systemic_importance_max
Upper bound on CAMEO+ importance of the affected system. This selects Events with that CAMEO+ measurement.
Clear enough to supply this argument.
propagation_potential_min
Lower bound on CAMEO+ conditions allowing an effect to spread. This selects Events with that CAMEO+ measurement.
Clear enough to supply this argument.
propagation_potential_max
Upper bound on CAMEO+ conditions allowing an effect to spread. This selects Events with that CAMEO+ measurement.
Clear enough to supply this argument.
market_sensitivity_min
Lower bound on CAMEO+ market-relevant information rather than a price-move prediction. This selects Events with that CAMEO+ measurement.
Clear enough to supply this argument.
market_sensitivity_max
Upper bound on CAMEO+ market-relevant information rather than a price-move prediction. This selects Events with that CAMEO+ measurement.
Clear enough to supply this argument.
sort
'significance' ranks by canonical product importance; 'recent' ranks newest first.
Clear enough to supply this argument.
limit
Number of Event cards to return on this page; follow pagination.next_cursor for further results.
Clear enough to supply this argument.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
include_images
Retain source article image URLs on returned cards when available.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
include_entity_images
Retain linked entity thumbnails when include_images is enabled; otherwise this switch has no effect.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
recorded_start
Inclusive start of API publication time, as an ISO UTC timestamp. Supply both bounds. Includes late arrivals without changing when the event happened. Cannot combine with reporting-date filters. Event and Story lists return records first made available in this interval, not later updates to existing records. Use /api/v2/activity for changes.
Explain the meaning of this value, not just its name.
recorded_end
Exclusive end of API publication time, as an ISO UTC timestamp. Supply both bounds. Includes late arrivals without changing when the event happened. Cannot combine with reporting-date filters. Event and Story lists return records first made available in this interval, not later updates to existing records. Use /api/v2/activity for changes.
Explain the meaning of this value, not just its name.
entity_family
Which canonical ids the handle stands for. `expand` (default) also matches the sibling ids the entity arbiter has already merged into the same real-world entity — a Wikipedia identity minted twice under different URL spellings, for instance — and echoes the union back as `applied_filters.entity_ids_expanded`. `exact` restricts to the one canonical id the handle resolves to, reproducing the pre-2026-08-25 counts.
Explain the meaning of this value, not just its name.
geo_precision_min
Geo precision lower bound.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
geo_precision_max
Geo precision upper bound.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
include_total
Add `pagination.estimated_total` — how many events match the filters, ignoring the page. Off by default because it costs a second scan of the same window. Counted from the SAME filters and the same row source as the page, so it always describes the result set you are walking. It is `null` (not a number) on a `search=` request: semantic retrieval is bounded by a candidate cap, so any total there would describe the candidate pool rather than the matching events. Without it, `pagination.next_cursor` still tells you whether more rows exist — non-null means yes, null means the walk is finished.
Explain the meaning of this value, not just its name.
target_type
Typed selected root for a shared connected scope: entity or facility. Use with target_ids.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
target_ids
Comma-separated stable IDs for the selected roots (up to 25). Use with target_type; roots are unioned. Choices: get_parameter_options('search_events', 'target_ids').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
related_scope
direct matches the selected target. connected includes verified controlled subsidiaries for entities, or identified facility owners and authoritative parent paths for facilities.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
nearby_radius_km
Opt-in proximity for a facility target scope. Matches Events near any selected facility; this is separate from owner coverage and requires target_type=facility with related_scope=direct.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description80/100
Find maintained Situations by title, canonical entity or Story/Event membership. Country takes ISO-3 codes such as UKR, never country names such as Ukraine. Latest development sorting uses reporting dates and genuine first-observed evidence, never refresh time. totals describes lifetime membership; selected_scope and category_summaries describe requested reporting dates. Follow situation_uid with get_situation. Search is title term matching; entity takes a resolved ID. Country and category match the same member-linked coded Event, not primary Situation geography or actor nationality; both date bounds are required for these facets (maximum 30 days). Shared REST authentication and query quotas apply.
The description explains the capability, when to use it, and what to expect.
Inputs95/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
search
Free text matched against the stored `title` OR the headline of any member Story reported inside the window (the last 30 days when no dates are sent) — a case-insensitive match requiring EVERY whitespace-separated term to appear in one of the two, so `nepal flood` matches "Flash floods hit northern Nepal-Tibet border" and `AI slowdown` finds a Situation titled "Trump says US will not slow AI race" through a member headline that says slowdown. The phrase also runs through the hybrid `GET /api/v2/stories?search=` in the same window, and a Situation holding one of the top-ranked Stories matches too, so `AI pause` can reach the same Situation through meaning; `meta.search.semantic_story_candidates` reports how many Story hits that arm contributed and `meta.search.note` says when it was unavailable. What it CANNOT do: read article text or entities directly; and `title` is the PEAK member's headline, re-stamped every time the Situation is recomputed. At most 8 terms; more is refused with `INVALID_SEARCH` rather than silently truncated. To search what a Situation is actually ABOUT, run `GET /api/v2/stories?search=` and take any returned Story id to `/api/v2/situations/{story_id}`.
Clear enough to supply this argument.
entity
Canonical entity handle or name, using the same identity resolution as Stories. Requires both reporting date bounds, at most 30 days. Choices: get_parameter_options('search_situations', 'entity').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
story_id
Stored Situation UID from search_situations, or a member Story ID when supported by this operation; reuse the returned identifier. Choices: get_parameter_options('search_situations', 'story_id').
Clear enough to supply this argument.
event_uid
Coded Event UID from search_events; selects Situations with member Stories linked to that Event. Choices: get_parameter_options('search_situations', 'event_uid').
Clear enough to supply this argument.
country
Any member-linked coded Event located in this ISO-3 country. Actor nationality is not used. Requires date_start and date_end, at most 30 inclusive days. Both country and category match the SAME Event. Choices: get_parameter_options('search_situations', 'country').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
category
Any member-linked coded Event in this Event taxonomy category, not Story category or a primary Situation label. Requires both reporting date bounds, at most 30 days. Country and category match the same Event. Choices: get_parameter_options('search_situations', 'category').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
date_start
Return Situations still running on or after this date (YYYY-MM-DD) — matched against `span_end`, so an occurrence that began earlier and is ongoing IS returned. Optional and independent of `date_end`. There is no maximum span: the Situations table is one row per adjudicated occurrence and is small by construction, so this is a filter on a stored column rather than a bound on how much is scanned.
Clear enough to supply this argument.
date_end
Return Situations that had already begun by this date (YYYY-MM-DD) — matched against `span_start`. Sent together with `date_start` the pair selects every occurrence whose span OVERLAPS the window; sent alone it leaves the other side open. An inverted pair is refused with `INVALID_DATE_RANGE` rather than answered empty.
Clear enough to supply this argument.
min_stories
Minimum member Stories across the whole current servable membership, not the selected reporting window. The public discovery page sends min_stories=2&min_events=2; the API applies no minimum when omitted. Use min_stories=1&min_events=0 to include emerging seeds. This filter does not change creation, growth or direct UID lookup.
Clear enough to supply this argument.
min_articles
Minimum articles across the member Stories — the best single proxy for how big an occurrence got, and the default sort key. Compared against the stored `article_count`.
Clear enough to supply this argument.
min_events
Minimum coded Events at canonical-incident grain across the whole current servable membership. The public discovery page sends min_stories=2&min_events=2; the API applies no minimum when omitted. Use min_stories=1&min_events=0 to include emerging seeds, including reporting with no coded Events. Explicit zero is permitted.
Clear enough to supply this argument.
sort
Ranking. `recent` uses latest reporting date, then first-observed membership time; `created` orders by immutable creation time, newest first; `updated` orders by the latest serving-membership refresh; article_count, story_count and event_count are volume alternatives; `span_days` puts the longest-running occurrence first — the inclusive day count between `span.start` and `span.end`, with an unmeasured span last. Recent never uses refresh time or volume. Every order breaks ties on `situation_uid`, so paging with `offset` is stable.
Clear enough to supply this argument.
limit
Number of Situations returned on this page. `pagination.total` is the true number matching your filters, counted separately from the page, so `has_more` is measured rather than inferred from a full page.
Clear enough to supply this argument.
offset
Number of records to skip before this page.
Clear enough to supply this argument.
include_map
Include country aggregates over every matching Situation, independently of page size. Requires a reporting window of at most 30 days.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
Describe the returned fields so an agent can interpret the result.
View output schema
{
"if": {
"required": [
"_mcp_projection"
]
},
"else": {
"type": "object",
"required": [
"success",
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"description": "Stored Situation summary: situation_uid, title, span, counts and counts_updated_at. Counts cover the whole stored span, not only the search window."
},
"description": "Situation records."
},
"success": {
"type": "boolean"
},
"pagination": {
"type": "object",
"description": "Offset paging; use offset and limit, not a cursor."
},
"applied_filters": {
"type": "object",
"description": "Echo of the resolved filters; `ignored` lists dropped/unknown args."
}
},
"description": "List of Situation records."
},
"then": {
"type": "object",
"required": [
"_mcp_projection"
],
"properties": {
"data": {
"type": "array",
"description": "Compact records retain IDs, returned links, selected images, evidence and metrics where available; unknown values remain unknown."
},
"success": {
"type": "boolean"
},
"pagination": {
"type": "object",
"description": "Offset paging; use offset and limit, not a cursor."
},
"_mcp_projection": {
"type": "object",
"required": [
"mode"
],
"properties": {
"mode": {
"const": "compact"
},
"truncated": {
"type": "boolean"
}
},
"description": "Explicitly discloses omitted fields or shortened evidence."
},
"applied_filters": {
"type": "object",
"description": "Echo of the resolved filters; `ignored` lists dropped/unknown args."
}
}
},
"type": "object",
"description": "Full preserves the bounded API response. Compact preserves evidence, coverage, filters and pagination with explicit projection disclosure; neither fetches other pages."
}
Original tool metadata
{
"name": "search_situations",
"title": "GDELT Cloud: search situations",
"description": "Find maintained Situations by title, canonical entity or Story/Event membership. Country takes ISO-3 codes such as UKR, never country names such as Ukraine. Latest development sorting uses reporting dates and genuine first-observed evidence, never refresh time. totals describes lifetime membership; selected_scope and category_summaries describe requested reporting dates. Follow situation_uid with get_situation. Search is title term matching; entity takes a resolved ID. Country and category match the same member-linked coded Event, not primary Situation geography or actor nationality; both date bounds are required for these facets (maximum 30 days). Shared REST authentication and query quotas apply.",
"inputSchema": {
"type": "object",
"properties": {
"sort": {
"enum": [
"article_count",
"story_count",
"event_count",
"recent",
"created",
"updated",
"span_days"
],
"type": "string",
"default": "recent",
"description": "Ranking. `recent` uses latest reporting date, then first-observed membership time; `created` orders by immutable creation time, newest first; `updated` orders by the latest serving-membership refresh; article_count, story_count and event_count are volume alternatives; `span_days` puts the longest-running occurrence first — the inclusive day count between `span.start` and `span.end`, with an unmeasured span last. Recent never uses refresh time or volume. Every order breaks ties on `situation_uid`, so paging with `offset` is stable.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "situation_sort",
"parameter": "sort"
}
},
"limit": {
"type": "integer",
"default": 25,
"maximum": 200,
"minimum": 1,
"description": "Number of Situations returned on this page. `pagination.total` is the true number matching your filters, counted separately from the page, so `has_more` is measured rather than inferred from a full page."
},
"entity": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Canonical entity handle or name, using the same identity resolution as Stories. Requires both reporting date bounds, at most 30 days. Choices: get_parameter_options('search_situations', 'entity').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "identifier",
"enum_id": "entity_handle",
"parameter": "entity"
}
},
"offset": {
"type": "integer",
"default": 0,
"minimum": 0,
"description": "Number of records to skip before this page."
},
"search": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Free text matched against the stored `title` OR the headline of any member Story reported inside the window (the last 30 days when no dates are sent) — a case-insensitive match requiring EVERY whitespace-separated term to appear in one of the two, so `nepal flood` matches \"Flash floods hit northern Nepal-Tibet border\" and `AI slowdown` finds a Situation titled \"Trump says US will not slow AI race\" through a member headline that says slowdown. The phrase also runs through the hybrid `GET /api/v2/stories?search=` in the same window, and a Situation holding one of the top-ranked Stories matches too, so `AI pause` can reach the same Situation through meaning; `meta.search.semantic_story_candidates` reports how many Story hits that arm contributed and `meta.search.note` says when it was unavailable. What it CANNOT do: read article text or entities directly; and `title` is the PEAK member's headline, re-stamped every time the Situation is recomputed. At most 8 terms; more is refused with `INVALID_SEARCH` rather than silently truncated. To search what a Situation is actually ABOUT, run `GET /api/v2/stories?search=` and take any returned Story id to `/api/v2/situations/{story_id}`."
},
"country": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"default": null,
"description": "Any member-linked coded Event located in this ISO-3 country. Actor nationality is not used. Requires date_start and date_end, at most 30 inclusive days. Both country and category match the SAME Event. Choices: get_parameter_options('search_situations', 'country').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "identifier",
"enum_id": "country",
"parameter": "country"
}
},
"category": {
"anyOf": [
{
"type": "array",
"items": {
"enum": [
"Battles",
"Protests",
"Riots",
"Explosions/Remote violence",
"Violence against civilians",
"Strategic developments",
"POLITICAL",
"CRIME",
"ECONOMIC",
"CORPORATE",
"TECHNOLOGY",
"INFRASTRUCTURE",
"ENVIRONMENT",
"HEALTH",
"DEMOGRAPHIC",
"INFORMATION"
],
"type": "string"
}
},
{
"type": "null"
}
],
"default": null,
"description": "Any member-linked coded Event in this Event taxonomy category, not Story category or a primary Situation label. Requires both reporting date bounds, at most 30 days. Country and category match the same Event. Choices: get_parameter_options('search_situations', 'category').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "event_category",
"parameter": "category"
}
},
"date_end": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Return Situations that had already begun by this date (YYYY-MM-DD) — matched against `span_start`. Sent together with `date_start` the pair selects every occurrence whose span OVERLAPS the window; sent alone it leaves the other side open. An inverted pair is refused with `INVALID_DATE_RANGE` rather than answered empty."
},
"story_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Stored Situation UID from search_situations, or a member Story ID when supported by this operation; reuse the returned identifier. Choices: get_parameter_options('search_situations', 'story_id').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "identifier",
"parameter": "story_id"
}
},
"event_uid": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Coded Event UID from search_events; selects Situations with member Stories linked to that Event. Choices: get_parameter_options('search_situations', 'event_uid').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "identifier",
"parameter": "event_uid"
}
},
"date_start": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Return Situations still running on or after this date (YYYY-MM-DD) — matched against `span_end`, so an occurrence that began earlier and is ongoing IS returned. Optional and independent of `date_end`. There is no maximum span: the Situations table is one row per adjudicated occurrence and is small by construction, so this is a filter on a stored column rather than a bound on how much is scanned."
},
"min_events": {
"anyOf": [
{
"type": "integer",
"maximum": 4294967295,
"minimum": 0
},
{
"type": "null"
}
],
"default": null,
"description": "Minimum coded Events at canonical-incident grain across the whole current servable membership. The public discovery page sends min_stories=2&min_events=2; the API applies no minimum when omitted. Use min_stories=1&min_events=0 to include emerging seeds, including reporting with no coded Events. Explicit zero is permitted."
},
"include_map": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": false,
"description": "Include country aggregates over every matching Situation, independently of page size. Requires a reporting window of at most 30 days."
},
"min_stories": {
"anyOf": [
{
"type": "integer",
"maximum": 4294967295,
"minimum": 0
},
{
"type": "null"
}
],
"default": null,
"description": "Minimum member Stories across the whole current servable membership, not the selected reporting window. The public discovery page sends min_stories=2&min_events=2; the API applies no minimum when omitted. Use min_stories=1&min_events=0 to include emerging seeds. This filter does not change creation, growth or direct UID lookup."
},
"min_articles": {
"anyOf": [
{
"type": "integer",
"maximum": 4294967295,
"minimum": 0
},
{
"type": "null"
}
],
"default": null,
"description": "Minimum articles across the member Stories — the best single proxy for how big an occurrence got, and the default sort key. Compared against the stored `article_count`."
},
"response_mode": {
"enum": [
"compact",
"full"
],
"type": "string",
"default": "compact",
"description": "Compact chat projection or unchanged bounded full API response; neither fetches another page."
}
},
"additionalProperties": false
},
"outputSchema": {
"if": {
"required": [
"_mcp_projection"
]
},
"else": {
"type": "object",
"required": [
"success",
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"description": "Stored Situation summary: situation_uid, title, span, counts and counts_updated_at. Counts cover the whole stored span, not only the search window."
},
"description": "Situation records."
},
"success": {
"type": "boolean"
},
"pagination": {
"type": "object",
"description": "Offset paging; use offset and limit, not a cursor."
},
"applied_filters": {
"type": "object",
"description": "Echo of the resolved filters; `ignored` lists dropped/unknown args."
}
},
"description": "List of Situation records."
},
"then": {
"type": "object",
"required": [
"_mcp_projection"
],
"properties": {
"data": {
"type": "array",
"description": "Compact records retain IDs, returned links, selected images, evidence and metrics where available; unknown values remain unknown."
},
"success": {
"type": "boolean"
},
"pagination": {
"type": "object",
"description": "Offset paging; use offset and limit, not a cursor."
},
"_mcp_projection": {
"type": "object",
"required": [
"mode"
],
"properties": {
"mode": {
"const": "compact"
},
"truncated": {
"type": "boolean"
}
},
"description": "Explicitly discloses omitted fields or shortened evidence."
},
"applied_filters": {
"type": "object",
"description": "Echo of the resolved filters; `ignored` lists dropped/unknown args."
}
}
},
"type": "object",
"description": "Full preserves the bounded API response. Compact preserves evidence, coverage, filters and pagination with explicit projection disclosure; neither fetches other pages."
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description94/100
Retrieve a bounded reporting sample. For counts or period comparisons, call summarize_stories first with identical structured filters. Use summarize_events for Event metrics, then sample relevant Stories for evidence. A Story mention or passenger-service disruption does not prove freight impact. Continuous stories coverage begins 2026-03-08. Use consecutive windows of at most 30 inclusive days; a calendar month can be too long. Finish pagination.next_cursor within each fixed window before starting the next chunk without a cursor. Without an explicit window, entity filters default to 30 days and other queries to the last 24 hours. meta.query_window reports the effective predicates; meta.coverage describes the available corpus. Search v2 clustered Stories when the user needs narrative clusters and article evidence. Supports plain-English geography whose region/continent filters expand to country lists and match through linked Event location, optional admin1, linked Event category/subcategory filters, linked-event/fatality filters, article_count_min/article_count_max, true embedding semantic search, and significance or recent sorting. Returns Story cards with public GDELT Cloud URLs, linked Events/Entities, top 3 articles inline, source favicons, article sharing images, and linked Entity thumbnails when available. Entity matching uses coverage: the entity appears in the Story, which does not establish that it is a party to its events. For ongoing collectors and company watches, discover get_activity (recorded time) and read_resource skill://building-with-api/SKILL.md before coding checkpoints; reporting-date searches are not an arrival feed. Country matching defaults to location_or_actor_origin; for territorial scope use country_match=location and check the echo on both news surfaces.
The description explains the capability, when to use it, and what to expect.
Inputs90/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
start_date
Inclusive start date in YYYY-MM-DD. With end_date, defines an explicit MCP Story window of at most 30 days.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
end_date
Inclusive end date in YYYY-MM-DD. With days only, start_date is computed as the trailing window ending here. Defaults to today UTC.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
days
Window days. Omit for the REST default: 30 days with entity, rolling past 24 hours otherwise. Set only to deliberately change that window.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
country
One or more plain-English country names or ISO-3 codes; legacy FIPS aliases also accepted. Filters Stories through linked-Event location. For a single country pass a one-element list: country=['United States']. Choices: get_parameter_options('search_stories', 'country').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
region
One plain-English region (Middle East, Europe, South Asia, Western Africa, …). Expanded to its ISO-3 country list and applied the same way as `country`.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
continent
One plain-English continent (Asia, Europe, Africa, North America, South America, Oceania). Expanded to its ISO-3 country list and applied the same way as `country`.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
admin1
Optional state/province/admin1 name discovered with list_admin1. Filters Story/Event location only, not actor origin. Choices: get_parameter_options('search_stories', 'admin1').
ISO source-language filter, e.g. ['ar','zh','en']. Restricts Stories to those with source-article coverage in these languages, for comparing narrative coverage across language spheres. Omit for all languages. Choices: get_parameter_options('search_stories', 'languages').
Clear enough to supply this argument.
entity
Resolved terminal entity id, news id, or name. Uses the same shared resolver as Events and entity products. Choices: get_parameter_options('search_stories', 'entity').
Clear enough to supply this argument.
entity_match
Entity matching uses coverage through a linked Story. The entity appears in that Story; this does not establish that it is an actor or party to the Event. Omit to inherit the API default, or explicitly select coverage.
Clear enough to supply this argument.
office
Political office ID (Q… or p_…), resolved with offices_search. Matches published term holders overlapping the reporting window or office_as_of. Unioned with entity=; refuses >1,000 holders. applied_filters.office_holders reports unresolved news identities. Actor context, not screening. Choices: get_parameter_options('search_stories', 'office').
Clear enough to supply this argument.
office_as_of
Valid-time date for office= (YYYY-MM-DD): who held it on this publisher-stated date. Separate from reporting dates and knowledge-time replay. Missing term evidence is excluded, never guessed.
Clear enough to supply this argument.
category
One category string from linked Event taxonomy. Use categories for multiple choices. Choices: get_parameter_options('search_stories', 'category').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
categories
JSON array (OR combined), e.g. ["INFRASTRUCTURE", "ECONOMIC"], not a JSON-encoded string. Choices: get_parameter_options('search_stories', 'categories').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
subcategory
Linked-Event subcategory string validated at runtime and scoped by category/categories. Conflict values are labels such as Peaceful protest; CAMEO+ values should be stable codes such as TE01 or IN03, with codebook labels accepted as legacy aliases. Choices: get_parameter_options('search_stories', 'subcategory').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
story_category
Legacy Story-cluster category such as 'conflict_security'. Prefer linked Event category/subcategory for product taxonomy filtering. Choices: get_parameter_options('search_stories', 'story_category').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
event_category
Deprecated alias for category. Prefer category='Battles' or category='CRIME'.
Clear enough to supply this argument.
event_categories
Deprecated alias for categories. Prefer categories=[...].
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
domain
Deprecated legacy linked CAMEO+ domain filter. Prefer category='DEMOGRAPHIC' and other category values for new integrations.
Clear enough to supply this argument.
search
Search text. With search_mode=lexical this is a literal phrase in served Events title/summary or Stories title. By default the complete phrase is checked against name/title evidence and is also embedded for vector ranking; literal matches rank first and remaining results are conceptual neighbours. There is no boolean parser: a query shaped `a OR b` is reduced to its first term and the response says so. Costs an embedding call and can return 503 SEMANTIC_SEARCH_UNAVAILABLE.
Clear enough to supply this argument.
search_mode
Search interpretation. semantic is a bounded hybrid search: complete-phrase name/title matches rank ahead of vector-ranked conceptual neighbours. lexical filters the complete serving set for a case-insensitive literal phrase in Events title/summary or Stories title before pagination; no stemming or boolean parsing. Lexical mode requires a supported serving snapshot and never falls back to the warehouse.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
country_match
Which definition of "in this country" the `country` / `region` / `continent` filters use. Applies to `region` and `continent` too, since both expand into the same country set. Note that `group_by=country` buckets on the event's own location, while the default match also admits actor origin — so a filtered total and the bucket for that same country can differ. Pass `country_match=location` when you need the two to agree.
Clear enough to supply this argument.
has_events
Default unset returns BOTH narrative Stories and event-coded Stories — prefer this for broader coverage. Stories represent narrative clusters; not every cluster has yet been coded as a structured Event, so requiring events silently drops the majority of relevant stories. Only set true when the analysis specifically needs structured-event metrics (significance, goldstein, fatalities, etc.). Set false to isolate narrative-only clusters — useful for comparing narrative coverage to coded events on the same topic.
Clear enough to supply this argument.
has_fatalities
Set true when Stories must link to fatal Events. Implies has_events=true and inherits the same coverage tradeoff — drops narrative-only stories.
Clear enough to supply this argument.
civilian_targeting
Set true when Stories must link to Conflict Events where ACLED civilian_targeting is populated. Implies structured linked-event evidence.
Clear enough to supply this argument.
article_count_min
Minimum Story article count. Use 1 for emerging stories; raise for higher-volume coverage.
Clear enough to supply this argument.
article_count_max
Maximum Story article count. Useful to avoid high-volume noise or find emerging low-volume stories.
Clear enough to supply this argument.
sort
'significance' ranks by canonical product importance; 'recent' ranks newest first.
Clear enough to supply this argument.
limit
Number of Story cards to return. Each card includes top 3 inline articles only.
Clear enough to supply this argument.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
include_images
Retain source article image URLs on returned cards when available.
Clear enough to supply this argument.
include_entity_images
Retain linked entity thumbnails when include_images is enabled; otherwise this switch has no effect.
Clear enough to supply this argument.
related
Attach a `related` block to each Story: the distinct Stories belonging to the same ongoing situation, with a count and their combined article total. A border crossing and the government's response to it are two Stories in one situation — both stay separately retrievable. Set false to skip the lookup.
Clear enough to supply this argument.
recorded_start
Inclusive start of API publication time, as an ISO UTC timestamp. Supply both bounds. Includes late arrivals without changing when the event happened. Cannot combine with reporting-date filters. Event and Story lists return records first made available in this interval, not later updates to existing records. Use /api/v2/activity for changes.
Clear enough to supply this argument.
recorded_end
Exclusive end of API publication time, as an ISO UTC timestamp. Supply both bounds. Includes late arrivals without changing when the event happened. Cannot combine with reporting-date filters. Event and Story lists return records first made available in this interval, not later updates to existing records. Use /api/v2/activity for changes.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
entity_family
Which canonical ids the handle stands for. `expand` (default) also matches the sibling ids the entity arbiter has already merged into the same real-world entity — a Wikipedia identity minted twice under different URL spellings, for instance — and echoes the union back as `applied_filters.entity_ids_expanded`. `exact` restricts to the one canonical id the handle resolves to, reproducing the pre-2026-08-25 counts.
Clear enough to supply this argument.
target_type
Typed selected root for a shared connected scope: entity or facility. Use with target_ids.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
target_ids
Comma-separated stable IDs for the selected roots (up to 25). Use with target_type; roots are unioned. Choices: get_parameter_options('search_stories', 'target_ids').
Clear enough to supply this argument.
related_scope
direct matches the selected target. connected includes verified controlled subsidiaries for entities, or identified facility owners and authoritative parent paths for facilities.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description97/100
Persist the running or paused state of an organization Monitor; requires Monitor-management access and current running-slot entitlement. First enablement establishes the starting checkpoint without delivering Preview history. Returns the updated Monitor receipt.
The description explains the capability, when to use it, and what to expect.
Inputs92/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
monitor_id
Organization Monitor UUID returned by create_monitor or list_monitors; select a Monitor in the connected organization. Choices: get_parameter_options('set_monitor_enabled', 'monitor_id').
Clear enough to supply this argument.
enabled
True to run; false to pause.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description81/100
For occurrences inside a country, explicitly set country_match=location on both periods; the default also includes actor origins abroad. Compare identical filters and all four core metrics. A broad Infrastructure category count is not transport disruption: select the relevant taxonomy subcategory and group_by=subcategory before making that claim. Then search_events for evidence. Continuous events coverage begins 2026-03-01. Use consecutive windows of at most 30 inclusive days; a calendar month can be too long. This summary endpoint does not support cursor pagination; request each date chunk separately. Without an explicit window, entity filters default to 30 days and other queries to the last 24 hours. meta.query_window reports the effective predicates; meta.coverage describes the available corpus. Quantify GDELT Cloud Event counts and aggregates by date, geography or taxonomy before sampling evidence. Use group_by='subcategory' under a parent category such as Battles to discover ACLED sub-event buckets like Government regains territory, then reuse category+subcategory in search_events. Accepts the same structured and metric filters as search_events except semantic search. Returns counts plus grouped aggregate statistics. Favor the four core metrics: CAMEO+ magnitude, systemic importance, propagation potential and market sensitivity; significance is a ranking aid, not a disruption-pressure index. Use returned non-null metric counts and coverage; do not average displayed samples or unrelated categories. Hide coding confidence in ordinary answers. Additional evidence includes fatalities and article counts. For country/region briefs read_resource skill://news-country-research/SKILL.md. Compare the requested subtype, not all parent-category Events; discover subcategory buckets first and keep identical filters across windows. Use for comparable filtered populations, not totals inferred from sampled pages; counts describe reporting, not independently verified damage.
The description explains the capability, when to use it, and what to expect.
Inputs96/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
group_by
Dashboard grouping dimension. Use 'date' for trend lines, geography for maps, category for top taxonomy buckets, and subcategory to discover scoped drilldowns such as Battles -> Government regains territory. The two actor dimensions bucket by actor ORIGIN rather than by where the event happened — pair source_actor_country with a source filter to answer 'X acted on whom, ranked' in one call. Buckets include aggregate metrics used in significance scoring. NOTE: summarize_stories does NOT accept the actor dimensions — a Story has no source/target actor of its own.
Clear enough to supply this argument.
start_date
Inclusive start date in YYYY-MM-DD. With end_date, defines an explicit MCP summary window of at most 30 days.
Clear enough to supply this argument.
end_date
Inclusive end date in YYYY-MM-DD. With days only, start_date is computed as the trailing window ending here. Defaults to today UTC.
Clear enough to supply this argument.
days
Calendar-date window ending today, in days (max 30). `window=7d` and `days=7` are equivalent. When omitted, a request without entity filters uses the last 24 hours; entity filters use 30 days. Read meta.query_window for the actual bounds. There is no equivalent numeric default: sending days explicitly selects calendar dates and removes the implicit observed-time bound. Pass `days` explicitly, or `date_start`/`date_end`, whenever the window matters.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
country
One or more plain-English country names or ISO-3 codes; legacy FIPS aliases also accepted. Same OR'd location-or-actor-origin semantics as search_events. For a single country pass a one-element list: country=['United States']. Choices: get_parameter_options('summarize_events', 'country').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
source_actor_country
Acting side origin countries (names or ISO-3). Pair with target_actor_country for directional queries, e.g. China acting on the United States. CAMEO+ source actors perform the action; Conflict Events name the primary actor, not necessarily the initiator. Choices: get_parameter_options('summarize_events', 'source_actor_country').
Clear enough to supply this argument.
target_actor_country
WHO WAS ACTED ON. Origin country of the RECEIVING side. Direction matters. Combine with source_actor_country to select the acting and receiving sides independently. Choices: get_parameter_options('summarize_events', 'target_actor_country').
Clear enough to supply this argument.
actor_country
EITHER side, ignoring direction — the actor-origin half of `country` on its own. Use it to exclude events that merely HAPPENED in a country with no actor from it. Choices: get_parameter_options('summarize_events', 'actor_country').
Clear enough to supply this argument.
region
One plain-English region (Middle East, Europe, South Asia, Western Africa, …). Expanded to its ISO-3 country list and applied the same way as `country`.
Clear enough to supply this argument.
continent
One plain-English continent (Asia, Europe, Africa, North America, South America, Oceania). Expanded to its ISO-3 country list and applied the same way as `country`.
Clear enough to supply this argument.
admin1
Optional state/province/admin1 name discovered with list_admin1. Filters Event location only. Choices: get_parameter_options('summarize_events', 'admin1').
Clear enough to supply this argument.
event_family
Deprecated legacy filter. Prefer category/categories, which imply Conflict vs CAMEO+. Still accepted for backwards compatibility.
Clear enough to supply this argument.
category
One category string, e.g. Battles or INFRASTRUCTURE. Use categories for multiple choices. Choices: get_parameter_options('summarize_events', 'category').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
categories
JSON array (OR combined), e.g. ["INFRASTRUCTURE", "ECONOMIC"], not a JSON-encoded string. Choices: get_parameter_options('summarize_events', 'categories').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
subcategory
Event subcategory string validated at runtime, scoped by category/categories. For CAMEO+ categories, prefer stable event codes such as TE01 or IN03; codebook labels are accepted as legacy aliases. Choices: get_parameter_options('summarize_events', 'subcategory').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
domain
Deprecated legacy CAMEO+ domain filter. Prefer category/categories for new integrations.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
has_fatalities
Set true to summarize only Events with fatalities; no fatality min/max filters exist.
Clear enough to supply this argument.
civilian_targeting
Set true to summarize only Conflict Events where ACLED civilian_targeting is populated; set false to exclude those events.
Clear enough to supply this argument.
significance_min
Lower bound on canonical Event importance across coding families.
Clear enough to supply this argument.
significance_max
Upper bound on canonical Event importance across coding families.
Clear enough to supply this argument.
confidence_min
Lower bound on coding confidence rather than a probability of the real-world outcome.
Clear enough to supply this argument.
confidence_max
Upper bound on coding confidence rather than a probability of the real-world outcome.
Clear enough to supply this argument.
goldstein_scale_min
Lower bound on signed conflict/cooperation score; negative values describe conflictual actions, positive values cooperation; meaningful for Conflict and CAMEO+ POLITICAL.
Clear enough to supply this argument.
goldstein_scale_max
Upper bound on signed conflict/cooperation score; negative values describe conflictual actions, positive values cooperation; meaningful for Conflict and CAMEO+ POLITICAL.
Clear enough to supply this argument.
magnitude_min
Lower bound on CAMEO+ scale of the change or action. This selects Events with that CAMEO+ measurement.
Clear enough to supply this argument.
magnitude_max
Upper bound on CAMEO+ scale of the change or action. This selects Events with that CAMEO+ measurement.
Clear enough to supply this argument.
systemic_importance_min
Lower bound on CAMEO+ importance of the affected system. This selects Events with that CAMEO+ measurement.
Clear enough to supply this argument.
systemic_importance_max
Upper bound on CAMEO+ importance of the affected system. This selects Events with that CAMEO+ measurement.
Clear enough to supply this argument.
propagation_potential_min
Lower bound on CAMEO+ conditions allowing an effect to spread. This selects Events with that CAMEO+ measurement.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
propagation_potential_max
Upper bound on CAMEO+ conditions allowing an effect to spread. This selects Events with that CAMEO+ measurement.
Clear enough to supply this argument.
market_sensitivity_min
Lower bound on CAMEO+ market-relevant information rather than a price-move prediction. This selects Events with that CAMEO+ measurement.
Clear enough to supply this argument.
market_sensitivity_max
Upper bound on CAMEO+ market-relevant information rather than a price-move prediction. This selects Events with that CAMEO+ measurement.
Clear enough to supply this argument.
limit
Maximum number of summary buckets. Each bucket returns counts plus metrics/metric_stats with avg/max/min generated metric aggregates. There is no continuation cursor; narrow the window when this cap is reached.
Clear enough to supply this argument.
bbox
Bounding box `lat_min,lon_min,lat_max,lon_max`.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
country_match
Which definition of "in this country" the `country` / `region` / `continent` filters use. Applies to `region` and `continent` too, since both expand into the same country set. Note that `group_by=country` buckets on the event's own location, while the default match also admits actor origin — so a filtered total and the bucket for that same country can differ. Pass `country_match=location` when you need the two to agree.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
entity
Restrict to an entity's resolved coverage. Accepts a spine id (`e_…`), a news id (`wiki:…`) or a name, resolved through the shared arbiter so the same handle means the same entity on every endpoint. Accepts up to 25 comma-separated handles, which are UNIONED: a row is returned if ANY handle matches, never only the rows matching all of them. Every handle resolves through that same arbiter, so a handle means the same entity alone or in a list. A handle that resolves to nothing contributes nothing — it never widens the result — and is named in `applied_filters.entity_handles_unresolved`. More than 25 handles is refused with 400 MULTIPLE_ENTITY_HANDLES rather than truncated. Choices: get_parameter_options('summarize_events', 'entity').
Clear enough to supply this argument.
entity_family
Which canonical ids the handle stands for. `expand` (default) also matches the sibling ids the entity arbiter has already merged into the same real-world entity — a Wikipedia identity minted twice under different URL spellings, for instance — and echoes the union back as `applied_filters.entity_ids_expanded`. `exact` restricts to the one canonical id the handle resolves to, reproducing the pre-2026-08-25 counts.
Clear enough to supply this argument.
entity_match
Coverage matching: Stories mentioning or linking the entity and the Events those Stories carry. The default and only supported policy; it does not establish actor participation or material involvement.
Clear enough to supply this argument.
geo_precision_min
Geo precision lower bound.
Clear enough to supply this argument.
geo_precision_max
Geo precision upper bound.
Clear enough to supply this argument.
languages
Coverage-language filter (ISO 639-1/2) on the underlying articles. Choices: get_parameter_options('summarize_events', 'languages').
Clear enough to supply this argument.
near
Point proximity `lat,lon`, combined with `radius_km`. The box is used for index pruning and rows are refined by true great-circle distance.
Clear enough to supply this argument.
office
Restrict to the OFFICE-HOLDERS of a political office: the Wikidata QID of the office (`Q…`) or the `p_…` id `/api/v2/offices` serves. Resolves to every holder whose published term overlaps the window (or `office_as_of`, when sent), then scopes exactly as `entity=<those holders>` would — a row is returned if ANY holder matches, and it is UNIONED with `entity=` when both are sent. A name is refused with 400; resolve it with `GET /api/v2/offices?q=` first. A roster of more than 1,000 holders inside the window is refused with 400 OFFICE_SCOPE_TOO_LARGE, never truncated. Holders reach the news layer only through a Wikipedia identity, so `applied_filters.office_holders` discloses how many of the roster are `bridged_to_news` versus `unbridged` — an unbridged holder carries no key coverage matching can match on and contributes no rows, so the counts are a FLOOR on the office's real coverage rather than a measurement of it. Each matched row carries `entity_link.via: "office"` with `entity_link.entity` naming the HOLDER (a spine id), not the office. Choices: get_parameter_options('summarize_events', 'office').
Clear enough to supply this argument.
office_as_of
VALID TIME for `office=` — scope to whoever held the office ON this date (YYYY-MM-DD) rather than to everyone whose term overlaps the window. This is the publisher's start/end clock, not what we knew then: it is NOT the knowledge-time `as_of` and is not gated by it. Office-holders with no published start date cannot be placed on a date and are excluded (counted in `applied_filters.office_holders.undated_excluded`), never fabricated. Ignored without `office`.
Clear enough to supply this argument.
radius_km
Distance in kilometres from the selected point for geographic proximity matching.
Clear enough to supply this argument.
search
Case-insensitive literal phrase in Event title/summary or Story title.
Clear enough to supply this argument.
search_mode
Explicit lexical required with search.
Clear enough to supply this argument.
target_type
Typed selected root for a shared connected scope: entity or facility. Use with target_ids.
Clear enough to supply this argument.
target_ids
Comma-separated stable IDs for the selected roots (up to 25). Use with target_type; roots are unioned. Choices: get_parameter_options('summarize_events', 'target_ids').
Clear enough to supply this argument.
related_scope
direct matches the selected target. connected includes verified controlled subsidiaries for entities, or identified facility owners and authoritative parent paths for facilities.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
{
"name": "summarize_events",
"title": "GDELT Cloud: summarize events",
"description": "For occurrences inside a country, explicitly set country_match=location on both periods; the default also includes actor origins abroad. Compare identical filters and all four core metrics. A broad Infrastructure category count is not transport disruption: select the relevant taxonomy subcategory and group_by=subcategory before making that claim. Then search_events for evidence. Continuous events coverage begins 2026-03-01. Use consecutive windows of at most 30 inclusive days; a calendar month can be too long. This summary endpoint does not support cursor pagination; request each date chunk separately. Without an explicit window, entity filters default to 30 days and other queries to the last 24 hours. meta.query_window reports the effective predicates; meta.coverage describes the available corpus. Quantify GDELT Cloud Event counts and aggregates by date, geography or taxonomy before sampling evidence. Use group_by='subcategory' under a parent category such as Battles to discover ACLED sub-event buckets like Government regains territory, then reuse category+subcategory in search_events. Accepts the same structured and metric filters as search_events except semantic search. Returns counts plus grouped aggregate statistics. Favor the four core metrics: CAMEO+ magnitude, systemic importance, propagation potential and market sensitivity; significance is a ranking aid, not a disruption-pressure index. Use returned non-null metric counts and coverage; do not average displayed samples or unrelated categories. Hide coding confidence in ordinary answers. Additional evidence includes fatalities and article counts. For country/region briefs read_resource skill://news-country-research/SKILL.md. Compare the requested subtype, not all parent-category Events; discover subcategory buckets first and keep identical filters across windows. Use for comparable filtered populations, not totals inferred from sampled pages; counts describe reporting, not independently verified damage.",
"inputSchema": {
"type": "object",
"properties": {
"bbox": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Bounding box `lat_min,lon_min,lat_max,lon_max`."
},
"days": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Calendar-date window ending today, in days (max 30). `window=7d` and `days=7` are equivalent. When omitted, a request without entity filters uses the last 24 hours; entity filters use 30 days. Read meta.query_window for the actual bounds. There is no equivalent numeric default: sending days explicitly selects calendar dates and removes the implicit observed-time bound. Pass `days` explicitly, or `date_start`/`date_end`, whenever the window matters."
},
"near": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Point proximity `lat,lon`, combined with `radius_km`. The box is used for index pruning and rows are refined by true great-circle distance."
},
"limit": {
"type": "integer",
"default": 50,
"maximum": 500,
"minimum": 1,
"description": "Maximum number of summary buckets. Each bucket returns counts plus metrics/metric_stats with avg/max/min generated metric aggregates. There is no continuation cursor; narrow the window when this cap is reached."
},
"admin1": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional state/province/admin1 name discovered with list_admin1. Filters Event location only. Choices: get_parameter_options('summarize_events', 'admin1').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "observed",
"enum_id": "admin1",
"parameter": "admin1"
}
},
"domain": {
"anyOf": [
{
"enum": [
"POLITICAL",
"CRIME",
"ECONOMIC",
"CORPORATE",
"TECHNOLOGY",
"INFRASTRUCTURE",
"ENVIRONMENT",
"HEALTH",
"DEMOGRAPHIC",
"INFORMATION"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"deprecated": true,
"description": "Deprecated legacy CAMEO+ domain filter. Prefer category/categories for new integrations.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "cameoplus_domain",
"parameter": "domain"
}
},
"entity": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Restrict to an entity's resolved coverage. Accepts a spine id (`e_…`), a news id (`wiki:…`) or a name, resolved through the shared arbiter so the same handle means the same entity on every endpoint. Accepts up to 25 comma-separated handles, which are UNIONED: a row is returned if ANY handle matches, never only the rows matching all of them. Every handle resolves through that same arbiter, so a handle means the same entity alone or in a list. A handle that resolves to nothing contributes nothing — it never widens the result — and is named in `applied_filters.entity_handles_unresolved`. More than 25 handles is refused with 400 MULTIPLE_ENTITY_HANDLES rather than truncated. Choices: get_parameter_options('summarize_events', 'entity').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "identifier",
"enum_id": "entity_handle",
"parameter": "entity"
}
},
"office": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Restrict to the OFFICE-HOLDERS of a political office: the Wikidata QID of the office (`Q…`) or the `p_…` id `/api/v2/offices` serves. Resolves to every holder whose published term overlaps the window (or `office_as_of`, when sent), then scopes exactly as `entity=<those holders>` would — a row is returned if ANY holder matches, and it is UNIONED with `entity=` when both are sent. A name is refused with 400; resolve it with `GET /api/v2/offices?q=` first. A roster of more than 1,000 holders inside the window is refused with 400 OFFICE_SCOPE_TOO_LARGE, never truncated. Holders reach the news layer only through a Wikipedia identity, so `applied_filters.office_holders` discloses how many of the roster are `bridged_to_news` versus `unbridged` — an unbridged holder carries no key coverage matching can match on and contributes no rows, so the counts are a FLOOR on the office's real coverage rather than a measurement of it. Each matched row carries `entity_link.via: \"office\"` with `entity_link.entity` naming the HOLDER (a spine id), not the office. Choices: get_parameter_options('summarize_events', 'office').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "identifier",
"enum_id": "office_id",
"parameter": "office"
}
},
"region": {
"anyOf": [
{
"enum": [
"Africa",
"Asia",
"Middle East",
"Northern Africa",
"Western Africa",
"Eastern Africa",
"Middle Africa",
"Southern Africa",
"Europe",
"Eastern Europe",
"South Asia",
"Southeast Asia",
"East Asia",
"Central Asia",
"North America",
"Central America",
"Caribbean",
"South America",
"Oceania"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "One plain-English region (Middle East, Europe, South Asia, Western Africa, …). Expanded to its ISO-3 country list and applied the same way as `country`.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "region",
"parameter": "region"
}
},
"search": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Case-insensitive literal phrase in Event title/summary or Story title."
},
"country": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"default": null,
"description": "One or more plain-English country names or ISO-3 codes; legacy FIPS aliases also accepted. Same OR'd location-or-actor-origin semantics as search_events. For a single country pass a one-element list: country=['United States']. Choices: get_parameter_options('summarize_events', 'country').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "identifier",
"enum_id": "country",
"parameter": "country"
}
},
"category": {
"anyOf": [
{
"enum": [
"Battles",
"Protests",
"Riots",
"Explosions/Remote violence",
"Violence against civilians",
"Strategic developments",
"POLITICAL",
"CRIME",
"ECONOMIC",
"CORPORATE",
"TECHNOLOGY",
"INFRASTRUCTURE",
"ENVIRONMENT",
"HEALTH",
"DEMOGRAPHIC",
"INFORMATION"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "One category string, e.g. Battles or INFRASTRUCTURE. Use categories for multiple choices. Choices: get_parameter_options('summarize_events', 'category').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "event_category",
"parameter": "category"
}
},
"end_date": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Inclusive end date in YYYY-MM-DD. With days only, start_date is computed as the trailing window ending here. Defaults to today UTC."
},
"group_by": {
"enum": [
"date",
"country",
"region",
"continent",
"category",
"subcategory",
"source_actor_country",
"target_actor_country"
],
"type": "string",
"default": "date",
"description": "Dashboard grouping dimension. Use 'date' for trend lines, geography for maps, category for top taxonomy buckets, and subcategory to discover scoped drilldowns such as Battles -> Government regains territory. The two actor dimensions bucket by actor ORIGIN rather than by where the event happened — pair source_actor_country with a source filter to answer 'X acted on whom, ranked' in one call. Buckets include aggregate metrics used in significance scoring. NOTE: summarize_stories does NOT accept the actor dimensions — a Story has no source/target actor of its own.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "event_group_by",
"parameter": "group_by"
}
},
"continent": {
"anyOf": [
{
"enum": [
"Africa",
"Asia",
"Europe",
"North America",
"South America",
"Oceania"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "One plain-English continent (Asia, Europe, Africa, North America, South America, Oceania). Expanded to its ISO-3 country list and applied the same way as `country`.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "continent",
"parameter": "continent"
}
},
"languages": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"default": null,
"description": "Coverage-language filter (ISO 639-1/2) on the underlying articles. Choices: get_parameter_options('summarize_events', 'languages').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "observed",
"enum_id": "coverage_language",
"parameter": "languages"
}
},
"radius_km": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Distance in kilometres from the selected point for geographic proximity matching."
},
"categories": {
"anyOf": [
{
"type": "array",
"items": {
"enum": [
"Battles",
"Protests",
"Riots",
"Explosions/Remote violence",
"Violence against civilians",
"Strategic developments",
"POLITICAL",
"CRIME",
"ECONOMIC",
"CORPORATE",
"TECHNOLOGY",
"INFRASTRUCTURE",
"ENVIRONMENT",
"HEALTH",
"DEMOGRAPHIC",
"INFORMATION"
],
"type": "string"
}
},
{
"type": "null"
}
],
"default": null,
"description": "JSON array (OR combined), e.g. [\"INFRASTRUCTURE\", \"ECONOMIC\"], not a JSON-encoded string. Choices: get_parameter_options('summarize_events', 'categories').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "event_category",
"parameter": "categories"
}
},
"start_date": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Inclusive start date in YYYY-MM-DD. With end_date, defines an explicit MCP summary window of at most 30 days."
},
"target_ids": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Comma-separated stable IDs for the selected roots (up to 25). Use with target_type; roots are unioned. Choices: get_parameter_options('summarize_events', 'target_ids').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "identifier",
"parameter": "target_ids"
}
},
"search_mode": {
"anyOf": [
{
"type": "string",
"const": "lexical"
},
{
"type": "null"
}
],
"default": null,
"description": "Explicit lexical required with search.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "reporting_summary_search_mode",
"parameter": "search_mode"
}
},
"subcategory": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Event subcategory string validated at runtime, scoped by category/categories. For CAMEO+ categories, prefer stable event codes such as TE01 or IN03; codebook labels are accepted as legacy aliases. Choices: get_parameter_options('summarize_events', 'subcategory').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "event_subcategory",
"parameter": "subcategory",
"parent_parameter": "category"
}
},
"target_type": {
"anyOf": [
{
"enum": [
"entity",
"facility"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Typed selected root for a shared connected scope: entity or facility. Use with target_ids.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"parameter": "target_type"
}
},
"entity_match": {
"anyOf": [
{
"type": "string",
"const": "coverage"
},
{
"type": "null"
}
],
"default": null,
"description": "Coverage matching: Stories mentioning or linking the entity and the Events those Stories carry. The default and only supported policy; it does not establish actor participation or material involvement.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "entity_match",
"parameter": "entity_match"
}
},
"event_family": {
"anyOf": [
{
"enum": [
"conflict",
"cameoplus"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"deprecated": true,
"description": "Deprecated legacy filter. Prefer category/categories, which imply Conflict vs CAMEO+. Still accepted for backwards compatibility.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "event_family",
"parameter": "event_family"
}
},
"office_as_of": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "VALID TIME for `office=` — scope to whoever held the office ON this date (YYYY-MM-DD) rather than to everyone whose term overlaps the window. This is the publisher's start/end clock, not what we knew then: it is NOT the knowledge-time `as_of` and is not gated by it. Office-holders with no published start date cannot be placed on a date and are excluded (counted in `applied_filters.office_holders.undated_excluded`), never fabricated. Ignored without `office`."
},
"actor_country": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"default": null,
"description": "EITHER side, ignoring direction — the actor-origin half of `country` on its own. Use it to exclude events that merely HAPPENED in a country with no actor from it. Choices: get_parameter_options('summarize_events', 'actor_country').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "identifier",
"enum_id": "country",
"parameter": "actor_country"
}
},
"country_match": {
"anyOf": [
{
"enum": [
"location_or_actor_origin",
"location"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Which definition of \"in this country\" the `country` / `region` / `continent` filters use. Applies to `region` and `continent` too, since both expand into the same country set. Note that `group_by=country` buckets on the event's own location, while the default match also admits actor origin — so a filtered total and the bucket for that same country can differ. Pass `country_match=location` when you need the two to agree.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "country_match",
"parameter": "country_match"
}
},
"entity_family": {
"anyOf": [
{
"enum": [
"expand",
"exact"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Which canonical ids the handle stands for. `expand` (default) also matches the sibling ids the entity arbiter has already merged into the same real-world entity — a Wikipedia identity minted twice under different URL spellings, for instance — and echoes the union back as `applied_filters.entity_ids_expanded`. `exact` restricts to the one canonical id the handle resolves to, reproducing the pre-2026-08-25 counts.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "entity_family",
"parameter": "entity_family"
}
},
"magnitude_max": {
"anyOf": [
{
"type": "number",
"maximum": 10,
"minimum": 0
},
{
"type": "null"
}
],
"default": null,
"description": "Upper bound on CAMEO+ scale of the change or action. This selects Events with that CAMEO+ measurement."
},
"magnitude_min": {
"anyOf": [
{
"type": "number",
"maximum": 10,
"minimum": 0
},
{
"type": "null"
}
],
"default": null,
"description": "Lower bound on CAMEO+ scale of the change or action. This selects Events with that CAMEO+ measurement."
},
"related_scope": {
"anyOf": [
{
"enum": [
"direct",
"connected"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "direct matches the selected target. connected includes verified controlled subsidiaries for entities, or identified facility owners and authoritative parent paths for facilities.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"parameter": "related_scope"
}
},
"response_mode": {
"enum": [
"compact",
"full"
],
"type": "string",
"default": "compact",
"description": "Compact chat projection or unchanged bounded full API response; neither fetches another page."
},
"confidence_max": {
"anyOf": [
{
"type": "number",
"maximum": 1,
"minimum": 0
},
{
"type": "null"
}
],
"default": null,
"description": "Upper bound on coding confidence rather than a probability of the real-world outcome."
},
"confidence_min": {
"anyOf": [
{
"type": "number",
"maximum": 1,
"minimum": 0
},
{
"type": "null"
}
],
"default": null,
"description": "Lower bound on coding confidence rather than a probability of the real-world outcome."
},
"has_fatalities": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Set true to summarize only Events with fatalities; no fatality min/max filters exist."
},
"significance_max": {
"anyOf": [
{
"type": "number",
"maximum": 1,
"minimum": 0
},
{
"type": "null"
}
],
"default": null,
"description": "Upper bound on canonical Event importance across coding families."
},
"significance_min": {
"anyOf": [
{
"type": "number",
"maximum": 1,
"minimum": 0
},
{
"type": "null"
}
],
"default": null,
"description": "Lower bound on canonical Event importance across coding families."
},
"geo_precision_max": {
"anyOf": [
{
"type": "number",
"maximum": 3,
"minimum": 1
},
{
"type": "null"
}
],
"default": null,
"description": "Geo precision upper bound."
},
"geo_precision_min": {
"anyOf": [
{
"type": "number",
"maximum": 3,
"minimum": 1
},
{
"type": "null"
}
],
"default": null,
"description": "Geo precision lower bound."
},
"civilian_targeting": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Set true to summarize only Conflict Events where ACLED civilian_targeting is populated; set false to exclude those events."
},
"goldstein_scale_max": {
"anyOf": [
{
"type": "number",
"maximum": 10,
"minimum": -10
},
{
"type": "null"
}
],
"default": null,
"description": "Upper bound on signed conflict/cooperation score; negative values describe conflictual actions, positive values cooperation; meaningful for Conflict and CAMEO+ POLITICAL."
},
"goldstein_scale_min": {
"anyOf": [
{
"type": "number",
"maximum": 10,
"minimum": -10
},
{
"type": "null"
}
],
"default": null,
"description": "Lower bound on signed conflict/cooperation score; negative values describe conflictual actions, positive values cooperation; meaningful for Conflict and CAMEO+ POLITICAL."
},
"source_actor_country": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"default": null,
"description": "Acting side origin countries (names or ISO-3). Pair with target_actor_country for directional queries, e.g. China acting on the United States. CAMEO+ source actors perform the action; Conflict Events name the primary actor, not necessarily the initiator. Choices: get_parameter_options('summarize_events', 'source_actor_country').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "identifier",
"enum_id": "country",
"parameter": "source_actor_country"
}
},
"target_actor_country": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"default": null,
"description": "WHO WAS ACTED ON. Origin country of the RECEIVING side. Direction matters. Combine with source_actor_country to select the acting and receiving sides independently. Choices: get_parameter_options('summarize_events', 'target_actor_country').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "identifier",
"enum_id": "country",
"parameter": "target_actor_country"
}
},
"market_sensitivity_max": {
"anyOf": [
{
"type": "number",
"maximum": 1,
"minimum": 0
},
{
"type": "null"
}
],
"default": null,
"description": "Upper bound on CAMEO+ market-relevant information rather than a price-move prediction. This selects Events with that CAMEO+ measurement."
},
"market_sensitivity_min": {
"anyOf": [
{
"type": "number",
"maximum": 1,
"minimum": 0
},
{
"type": "null"
}
],
"default": null,
"description": "Lower bound on CAMEO+ market-relevant information rather than a price-move prediction. This selects Events with that CAMEO+ measurement."
},
"systemic_importance_max": {
"anyOf": [
{
"type": "number",
"maximum": 1,
"minimum": 0
},
{
"type": "null"
}
],
"default": null,
"description": "Upper bound on CAMEO+ importance of the affected system. This selects Events with that CAMEO+ measurement."
},
"systemic_importance_min": {
"anyOf": [
{
"type": "number",
"maximum": 1,
"minimum": 0
},
{
"type": "null"
}
],
"default": null,
"description": "Lower bound on CAMEO+ importance of the affected system. This selects Events with that CAMEO+ measurement."
},
"propagation_potential_max": {
"anyOf": [
{
"type": "number",
"maximum": 1,
"minimum": 0
},
{
"type": "null"
}
],
"default": null,
"description": "Upper bound on CAMEO+ conditions allowing an effect to spread. This selects Events with that CAMEO+ measurement."
},
"propagation_potential_min": {
"anyOf": [
{
"type": "number",
"maximum": 1,
"minimum": 0
},
{
"type": "null"
}
],
"default": null,
"description": "Lower bound on CAMEO+ conditions allowing an effect to spread. This selects Events with that CAMEO+ measurement."
}
},
"x-gdelt-taxonomy": {
"category_values": [
"Battles",
"Protests",
"Riots",
"Explosions/Remote violence",
"Violence against civilians",
"Strategic developments",
"POLITICAL",
"CRIME",
"ECONOMIC",
"CORPORATE",
"TECHNOLOGY",
"INFRASTRUCTURE",
"ENVIRONMENT",
"HEALTH",
"DEMOGRAPHIC",
"INFORMATION"
],
"subcategory_rule": "Subcategory is validated against its parent category/categories. Use stable returned codes; legacy labels are accepted aliases. Unknown choices fail before billing. For unfamiliar labels, search get_event_taxonomy with a known category and the default page size.",
"deprecated_params": [
"event_family",
"domain"
],
"subcategory_discovery": "Optional get_event_taxonomy(category=...) or get_parameter_options with parent_value scopes the choices; familiar valid filters need no lookup.",
"subcategory_category_params": [
"category",
"categories"
]
},
"additionalProperties": false,
"x-gdelt-errorRecovery": "If category or subcategory validation fails, choose from compact accepted_values when present, otherwise use nearest_values or run a subcategory summary.",
"x-gdelt-deprecatedParams": [
"event_family",
"domain"
],
"x-gdelt-subcategoryCategoryParams": [
"category",
"categories"
]
},
"outputSchema": {
"if": {
"required": [
"_mcp_projection"
]
},
"else": {
"type": "object",
"required": [
"success",
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Bucket value (e.g. the country / category)."
},
"metrics": {
"type": "object"
},
"group_by": {
"type": "string"
},
"fatalities": {
"type": [
"number",
"null"
]
},
"event_count": {
"type": "integer"
},
"metric_stats": {
"type": "object"
},
"article_count": {
"type": [
"integer",
"null"
]
}
},
"description": "One aggregate bucket. Counts: event_count, conflict_event_count, cameoplus_event_count, fatality_event_count, fatalities, article_count. Plus avg/min/max metric rollups and nested `metrics`/`metric_stats` (significance, goldstein, cameoplus, confidence, article_count, fatalities)."
}
},
"success": {
"type": "boolean"
},
"group_by": {
"type": "string"
},
"applied_filters": {
"type": "object"
}
},
"description": "Aggregate rollup grouped by `group_by` (one entry per bucket)."
},
"then": {
"type": "object",
"required": [
"_mcp_projection"
],
"properties": {
"data": {
"type": "array",
"description": "Compact records retain IDs, returned links, selected images, evidence and metrics where available; unknown values remain unknown."
},
"success": {
"type": "boolean"
},
"group_by": {
"type": "string"
},
"_mcp_projection": {
"type": "object",
"required": [
"mode"
],
"properties": {
"mode": {
"const": "compact"
},
"truncated": {
"type": "boolean"
}
},
"description": "Explicitly discloses omitted fields or shortened evidence."
},
"applied_filters": {
"type": "object"
}
}
},
"type": "object",
"description": "Full preserves the bounded API response. Compact preserves evidence, coverage, filters and pagination with explicit projection disclosure; neither fetches other pages."
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description96/100
Compare reporting counts with identical structured filters; use summarize_events for Event metrics. These are coverage statistics, not operational losses. Continuous stories coverage begins 2026-03-08. Use consecutive windows of at most 30 inclusive days; a calendar month can be too long. This summary endpoint does not support cursor pagination; request each date chunk separately. Without an explicit window, entity filters default to 30 days and other queries to the last 24 hours. meta.query_window reports the effective predicates; meta.coverage describes the available corpus. Summarize v2 Stories for dashboards, coverage maps, and trend charts. Use before drilling into Stories when the user asks for story counts, article volume, linked-event coverage, or fatality coverage by date, geography, category, or subcategory. Category/subcategory rollups use linked Event taxonomy, so they are good for coverage counts by Conflict event type or sub-event type. Does not accept semantic search. Returns grouped aggregate metric statistics: article counts, linked Event metrics, fatalities and recency. Favor the four core metrics when analyzing linked Events: magnitude, systemic importance, propagation potential and market sensitivity; significance is a ranking aid. Hide coding confidence in ordinary answers. Use returned non-null measurement counts; Story averages are coverage statistics, not an incident-risk index. For country/region briefs read_resource skill://news-country-research/SKILL.md.
The description explains the capability, when to use it, and what to expect.
Inputs94/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
group_by
Dashboard grouping dimension. Use 'date' for coverage trends, geography for maps, and category/subcategory for linked-Event taxonomy discovery. Category/subcategory Story rollups count event-linked coverage; date/geography keep broad narrative coverage.
Clear enough to supply this argument.
start_date
Inclusive start date in YYYY-MM-DD. With end_date, defines an explicit MCP Story summary window of at most 30 days.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
end_date
Inclusive end date in YYYY-MM-DD. With days only, start_date is computed as the trailing window ending here. Defaults to today UTC.
Clear enough to supply this argument.
days
Calendar-date window ending today, in days (max 30). `window=7d` and `days=7` are equivalent. When omitted, a request without entity filters uses the last 24 hours; entity filters use 30 days. Read meta.query_window for the actual bounds. There is no equivalent numeric default: sending days explicitly selects calendar dates and removes the implicit observed-time bound. Pass `days` explicitly, or `date_start`/`date_end`, whenever the window matters.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
country
One or more plain-English country names or ISO-3 codes; legacy FIPS aliases also accepted. Summarizes Stories through linked-Event location. For a single country pass a one-element list: country=['United States']. Choices: get_parameter_options('summarize_stories', 'country').
Clear enough to supply this argument.
region
One plain-English region (Middle East, Europe, South Asia, Western Africa, …). Expanded to its ISO-3 country list and applied the same way as `country`.
Clear enough to supply this argument.
continent
One plain-English continent (Asia, Europe, Africa, North America, South America, Oceania). Expanded to its ISO-3 country list and applied the same way as `country`.
Clear enough to supply this argument.
admin1
Optional state/province/admin1 name discovered with list_admin1. Choices: get_parameter_options('summarize_stories', 'admin1').
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
category
One category string from linked Event taxonomy. Use categories for multiple choices. Choices: get_parameter_options('summarize_stories', 'category').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
categories
JSON array (OR combined), e.g. ["INFRASTRUCTURE", "ECONOMIC"], not a JSON-encoded string. Choices: get_parameter_options('summarize_stories', 'categories').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
subcategory
Linked-Event subcategory string validated at runtime and scoped by category/categories. For CAMEO+ categories, prefer stable event codes such as TE01 or IN03; codebook labels are accepted as legacy aliases. Choices: get_parameter_options('summarize_stories', 'subcategory').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
story_category
Legacy Story-cluster category such as 'conflict_security'. Prefer linked Event category/subcategory for product taxonomy filtering. Choices: get_parameter_options('summarize_stories', 'story_category').
Clear enough to supply this argument.
event_category
Deprecated alias for category. Prefer category='Battles' or category='CRIME'.
Clear enough to supply this argument.
event_categories
Deprecated alias for categories. Prefer categories=[...].
Clear enough to supply this argument.
domain
Deprecated legacy linked CAMEO+ domain filter. Prefer category='DEMOGRAPHIC' and other category values for new integrations.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
has_events
Default unset summarizes both narrative Stories and event-coded Stories. Set true to focus on event-coded coverage; set false to focus on narrative-only clusters (useful for spotting topics where narrative volume outpaces event coding). Leaving unset is usually best for broad picture-of-coverage summaries.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
has_fatalities
Set true to summarize only Stories linked to fatal Events. Implies has_events=true.
Clear enough to supply this argument.
civilian_targeting
Set true to summarize only Stories linked to Conflict Events where ACLED civilian_targeting is populated.
Clear enough to supply this argument.
article_count_min
Minimum article count threshold for Story coverage.
Clear enough to supply this argument.
article_count_max
Maximum article count threshold for Story coverage.
Clear enough to supply this argument.
limit
Maximum number of summary buckets. Each bucket returns counts plus metrics/metric_stats with article count, recency, linked Event significance, and linked Event metric aggregates. There is no continuation cursor; narrow the window when this cap is reached.
Clear enough to supply this argument.
bbox
Bounding box `lat_min,lon_min,lat_max,lon_max`.
Clear enough to supply this argument.
country_attribution
For group_by=country: primary preserves one primary country per Story; all counts each Story under every authoritative country attribution or linked Event location/actor origin, using the same country_match and other filters as the Stories list. Explicit geographic filters also restrict the emitted country buckets. Buckets overlap and must not be summed as a global total. Other groupings ignore this option.
Clear enough to supply this argument.
country_match
Which definition of "in this country" the `country` / `region` / `continent` filters use. Applies to `region` and `continent` too, since both expand into the same country set. Note that `group_by=country` buckets on the event's own location, while the default match also admits actor origin — so a filtered total and the bucket for that same country can differ. Pass `country_match=location` when you need the two to agree.
Clear enough to supply this argument.
entity
Restrict to an entity's resolved coverage. Accepts a spine id (`e_…`), a news id (`wiki:…`) or a name, resolved through the shared arbiter so the same handle means the same entity on every endpoint. Accepts up to 25 comma-separated handles, which are UNIONED: a row is returned if ANY handle matches, never only the rows matching all of them. Every handle resolves through that same arbiter, so a handle means the same entity alone or in a list. A handle that resolves to nothing contributes nothing — it never widens the result — and is named in `applied_filters.entity_handles_unresolved`. More than 25 handles is refused with 400 MULTIPLE_ENTITY_HANDLES rather than truncated. Choices: get_parameter_options('summarize_stories', 'entity').
Clear enough to supply this argument.
entity_family
Which canonical ids the handle stands for. `expand` (default) also matches the sibling ids the entity arbiter has already merged into the same real-world entity — a Wikipedia identity minted twice under different URL spellings, for instance — and echoes the union back as `applied_filters.entity_ids_expanded`. `exact` restricts to the one canonical id the handle resolves to, reproducing the pre-2026-08-25 counts.
Clear enough to supply this argument.
entity_match
Coverage matching: Stories mentioning or linking the entity and the Events those Stories carry. The default and only supported policy; it does not establish actor participation or material involvement.
Clear enough to supply this argument.
languages
Coverage-language filter (ISO 639-1/2) on the underlying articles. Choices: get_parameter_options('summarize_stories', 'languages').
Clear enough to supply this argument.
office
Restrict to the OFFICE-HOLDERS of a political office: the Wikidata QID of the office (`Q…`) or the `p_…` id `/api/v2/offices` serves. Resolves to every holder whose published term overlaps the window (or `office_as_of`, when sent), then scopes exactly as `entity=<those holders>` would — a row is returned if ANY holder matches, and it is UNIONED with `entity=` when both are sent. A name is refused with 400; resolve it with `GET /api/v2/offices?q=` first. A roster of more than 1,000 holders inside the window is refused with 400 OFFICE_SCOPE_TOO_LARGE, never truncated. Holders reach the news layer only through a Wikipedia identity, so `applied_filters.office_holders` discloses how many of the roster are `bridged_to_news` versus `unbridged` — an unbridged holder carries no key coverage matching can match on and contributes no rows, so the counts are a FLOOR on the office's real coverage rather than a measurement of it. Each matched row carries `entity_link.via: "office"` with `entity_link.entity` naming the HOLDER (a spine id), not the office. Choices: get_parameter_options('summarize_stories', 'office').
Clear enough to supply this argument.
office_as_of
VALID TIME for `office=` — scope to whoever held the office ON this date (YYYY-MM-DD) rather than to everyone whose term overlaps the window. This is the publisher's start/end clock, not what we knew then: it is NOT the knowledge-time `as_of` and is not gated by it. Office-holders with no published start date cannot be placed on a date and are excluded (counted in `applied_filters.office_holders.undated_excluded`), never fabricated. Ignored without `office`.
Clear enough to supply this argument.
search
Case-insensitive literal phrase in Event title/summary or Story title.
Clear enough to supply this argument.
search_mode
Explicit lexical required with search.
Clear enough to supply this argument.
target_type
Typed selected root for a shared connected scope: entity or facility. Use with target_ids.
Clear enough to supply this argument.
target_ids
Comma-separated stable IDs for the selected roots (up to 25). Use with target_type; roots are unioned. Choices: get_parameter_options('summarize_stories', 'target_ids').
Clear enough to supply this argument.
related_scope
direct matches the selected target. connected includes verified controlled subsidiaries for entities, or identified facility owners and authoritative parent paths for facilities.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
{
"name": "summarize_stories",
"title": "GDELT Cloud: summarize stories",
"description": "Compare reporting counts with identical structured filters; use summarize_events for Event metrics. These are coverage statistics, not operational losses. Continuous stories coverage begins 2026-03-08. Use consecutive windows of at most 30 inclusive days; a calendar month can be too long. This summary endpoint does not support cursor pagination; request each date chunk separately. Without an explicit window, entity filters default to 30 days and other queries to the last 24 hours. meta.query_window reports the effective predicates; meta.coverage describes the available corpus. Summarize v2 Stories for dashboards, coverage maps, and trend charts. Use before drilling into Stories when the user asks for story counts, article volume, linked-event coverage, or fatality coverage by date, geography, category, or subcategory. Category/subcategory rollups use linked Event taxonomy, so they are good for coverage counts by Conflict event type or sub-event type. Does not accept semantic search. Returns grouped aggregate metric statistics: article counts, linked Event metrics, fatalities and recency. Favor the four core metrics when analyzing linked Events: magnitude, systemic importance, propagation potential and market sensitivity; significance is a ranking aid. Hide coding confidence in ordinary answers. Use returned non-null measurement counts; Story averages are coverage statistics, not an incident-risk index. For country/region briefs read_resource skill://news-country-research/SKILL.md.",
"inputSchema": {
"type": "object",
"properties": {
"bbox": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Bounding box `lat_min,lon_min,lat_max,lon_max`."
},
"days": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Calendar-date window ending today, in days (max 30). `window=7d` and `days=7` are equivalent. When omitted, a request without entity filters uses the last 24 hours; entity filters use 30 days. Read meta.query_window for the actual bounds. There is no equivalent numeric default: sending days explicitly selects calendar dates and removes the implicit observed-time bound. Pass `days` explicitly, or `date_start`/`date_end`, whenever the window matters."
},
"limit": {
"type": "integer",
"default": 50,
"maximum": 500,
"minimum": 1,
"description": "Maximum number of summary buckets. Each bucket returns counts plus metrics/metric_stats with article count, recency, linked Event significance, and linked Event metric aggregates. There is no continuation cursor; narrow the window when this cap is reached."
},
"admin1": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional state/province/admin1 name discovered with list_admin1. Choices: get_parameter_options('summarize_stories', 'admin1').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "observed",
"enum_id": "admin1",
"parameter": "admin1"
}
},
"domain": {
"anyOf": [
{
"enum": [
"POLITICAL",
"CRIME",
"ECONOMIC",
"CORPORATE",
"TECHNOLOGY",
"INFRASTRUCTURE",
"ENVIRONMENT",
"HEALTH",
"DEMOGRAPHIC",
"INFORMATION"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"deprecated": true,
"description": "Deprecated legacy linked CAMEO+ domain filter. Prefer category='DEMOGRAPHIC' and other category values for new integrations.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "cameoplus_domain",
"parameter": "domain"
}
},
"entity": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Restrict to an entity's resolved coverage. Accepts a spine id (`e_…`), a news id (`wiki:…`) or a name, resolved through the shared arbiter so the same handle means the same entity on every endpoint. Accepts up to 25 comma-separated handles, which are UNIONED: a row is returned if ANY handle matches, never only the rows matching all of them. Every handle resolves through that same arbiter, so a handle means the same entity alone or in a list. A handle that resolves to nothing contributes nothing — it never widens the result — and is named in `applied_filters.entity_handles_unresolved`. More than 25 handles is refused with 400 MULTIPLE_ENTITY_HANDLES rather than truncated. Choices: get_parameter_options('summarize_stories', 'entity').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "identifier",
"enum_id": "entity_handle",
"parameter": "entity"
}
},
"office": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Restrict to the OFFICE-HOLDERS of a political office: the Wikidata QID of the office (`Q…`) or the `p_…` id `/api/v2/offices` serves. Resolves to every holder whose published term overlaps the window (or `office_as_of`, when sent), then scopes exactly as `entity=<those holders>` would — a row is returned if ANY holder matches, and it is UNIONED with `entity=` when both are sent. A name is refused with 400; resolve it with `GET /api/v2/offices?q=` first. A roster of more than 1,000 holders inside the window is refused with 400 OFFICE_SCOPE_TOO_LARGE, never truncated. Holders reach the news layer only through a Wikipedia identity, so `applied_filters.office_holders` discloses how many of the roster are `bridged_to_news` versus `unbridged` — an unbridged holder carries no key coverage matching can match on and contributes no rows, so the counts are a FLOOR on the office's real coverage rather than a measurement of it. Each matched row carries `entity_link.via: \"office\"` with `entity_link.entity` naming the HOLDER (a spine id), not the office. Choices: get_parameter_options('summarize_stories', 'office').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "identifier",
"enum_id": "office_id",
"parameter": "office"
}
},
"region": {
"anyOf": [
{
"enum": [
"Africa",
"Asia",
"Middle East",
"Northern Africa",
"Western Africa",
"Eastern Africa",
"Middle Africa",
"Southern Africa",
"Europe",
"Eastern Europe",
"South Asia",
"Southeast Asia",
"East Asia",
"Central Asia",
"North America",
"Central America",
"Caribbean",
"South America",
"Oceania"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "One plain-English region (Middle East, Europe, South Asia, Western Africa, …). Expanded to its ISO-3 country list and applied the same way as `country`.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "region",
"parameter": "region"
}
},
"search": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Case-insensitive literal phrase in Event title/summary or Story title."
},
"country": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"default": null,
"description": "One or more plain-English country names or ISO-3 codes; legacy FIPS aliases also accepted. Summarizes Stories through linked-Event location. For a single country pass a one-element list: country=['United States']. Choices: get_parameter_options('summarize_stories', 'country').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "identifier",
"enum_id": "country",
"parameter": "country"
}
},
"category": {
"anyOf": [
{
"enum": [
"Battles",
"Protests",
"Riots",
"Explosions/Remote violence",
"Violence against civilians",
"Strategic developments",
"POLITICAL",
"CRIME",
"ECONOMIC",
"CORPORATE",
"TECHNOLOGY",
"INFRASTRUCTURE",
"ENVIRONMENT",
"HEALTH",
"DEMOGRAPHIC",
"INFORMATION"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "One category string from linked Event taxonomy. Use categories for multiple choices. Choices: get_parameter_options('summarize_stories', 'category').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "event_category",
"parameter": "category"
}
},
"end_date": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Inclusive end date in YYYY-MM-DD. With days only, start_date is computed as the trailing window ending here. Defaults to today UTC."
},
"group_by": {
"enum": [
"date",
"country",
"region",
"continent",
"category",
"subcategory"
],
"type": "string",
"default": "date",
"description": "Dashboard grouping dimension. Use 'date' for coverage trends, geography for maps, and category/subcategory for linked-Event taxonomy discovery. Category/subcategory Story rollups count event-linked coverage; date/geography keep broad narrative coverage.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "story_group_by",
"parameter": "group_by"
}
},
"continent": {
"anyOf": [
{
"enum": [
"Africa",
"Asia",
"Europe",
"North America",
"South America",
"Oceania"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "One plain-English continent (Asia, Europe, Africa, North America, South America, Oceania). Expanded to its ISO-3 country list and applied the same way as `country`.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "continent",
"parameter": "continent"
}
},
"languages": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"default": null,
"description": "Coverage-language filter (ISO 639-1/2) on the underlying articles. Choices: get_parameter_options('summarize_stories', 'languages').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "observed",
"enum_id": "coverage_language",
"parameter": "languages"
}
},
"categories": {
"anyOf": [
{
"type": "array",
"items": {
"enum": [
"Battles",
"Protests",
"Riots",
"Explosions/Remote violence",
"Violence against civilians",
"Strategic developments",
"POLITICAL",
"CRIME",
"ECONOMIC",
"CORPORATE",
"TECHNOLOGY",
"INFRASTRUCTURE",
"ENVIRONMENT",
"HEALTH",
"DEMOGRAPHIC",
"INFORMATION"
],
"type": "string"
}
},
{
"type": "null"
}
],
"default": null,
"description": "JSON array (OR combined), e.g. [\"INFRASTRUCTURE\", \"ECONOMIC\"], not a JSON-encoded string. Choices: get_parameter_options('summarize_stories', 'categories').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "event_category",
"parameter": "categories"
}
},
"has_events": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Default unset summarizes both narrative Stories and event-coded Stories. Set true to focus on event-coded coverage; set false to focus on narrative-only clusters (useful for spotting topics where narrative volume outpaces event coding). Leaving unset is usually best for broad picture-of-coverage summaries."
},
"start_date": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Inclusive start date in YYYY-MM-DD. With end_date, defines an explicit MCP Story summary window of at most 30 days."
},
"target_ids": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Comma-separated stable IDs for the selected roots (up to 25). Use with target_type; roots are unioned. Choices: get_parameter_options('summarize_stories', 'target_ids').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "identifier",
"parameter": "target_ids"
}
},
"search_mode": {
"anyOf": [
{
"type": "string",
"const": "lexical"
},
{
"type": "null"
}
],
"default": null,
"description": "Explicit lexical required with search.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "reporting_summary_search_mode",
"parameter": "search_mode"
}
},
"subcategory": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Linked-Event subcategory string validated at runtime and scoped by category/categories. For CAMEO+ categories, prefer stable event codes such as TE01 or IN03; codebook labels are accepted as legacy aliases. Choices: get_parameter_options('summarize_stories', 'subcategory').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "event_subcategory",
"parameter": "subcategory",
"parent_parameter": "category"
}
},
"target_type": {
"anyOf": [
{
"enum": [
"entity",
"facility"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Typed selected root for a shared connected scope: entity or facility. Use with target_ids.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"parameter": "target_type"
}
},
"entity_match": {
"anyOf": [
{
"type": "string",
"const": "coverage"
},
{
"type": "null"
}
],
"default": null,
"description": "Coverage matching: Stories mentioning or linking the entity and the Events those Stories carry. The default and only supported policy; it does not establish actor participation or material involvement.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "entity_match",
"parameter": "entity_match"
}
},
"office_as_of": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "VALID TIME for `office=` — scope to whoever held the office ON this date (YYYY-MM-DD) rather than to everyone whose term overlaps the window. This is the publisher's start/end clock, not what we knew then: it is NOT the knowledge-time `as_of` and is not gated by it. Office-holders with no published start date cannot be placed on a date and are excluded (counted in `applied_filters.office_holders.undated_excluded`), never fabricated. Ignored without `office`."
},
"country_match": {
"anyOf": [
{
"enum": [
"location_or_actor_origin",
"location"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Which definition of \"in this country\" the `country` / `region` / `continent` filters use. Applies to `region` and `continent` too, since both expand into the same country set. Note that `group_by=country` buckets on the event's own location, while the default match also admits actor origin — so a filtered total and the bucket for that same country can differ. Pass `country_match=location` when you need the two to agree.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "country_match",
"parameter": "country_match"
}
},
"entity_family": {
"anyOf": [
{
"enum": [
"expand",
"exact"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Which canonical ids the handle stands for. `expand` (default) also matches the sibling ids the entity arbiter has already merged into the same real-world entity — a Wikipedia identity minted twice under different URL spellings, for instance — and echoes the union back as `applied_filters.entity_ids_expanded`. `exact` restricts to the one canonical id the handle resolves to, reproducing the pre-2026-08-25 counts.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "entity_family",
"parameter": "entity_family"
}
},
"related_scope": {
"anyOf": [
{
"enum": [
"direct",
"connected"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "direct matches the selected target. connected includes verified controlled subsidiaries for entities, or identified facility owners and authoritative parent paths for facilities.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"parameter": "related_scope"
}
},
"response_mode": {
"enum": [
"compact",
"full"
],
"type": "string",
"default": "compact",
"description": "Compact chat projection or unchanged bounded full API response; neither fetches another page."
},
"event_category": {
"anyOf": [
{
"enum": [
"Battles",
"Protests",
"Riots",
"Explosions/Remote violence",
"Violence against civilians",
"Strategic developments",
"POLITICAL",
"CRIME",
"ECONOMIC",
"CORPORATE",
"TECHNOLOGY",
"INFRASTRUCTURE",
"ENVIRONMENT",
"HEALTH",
"DEMOGRAPHIC",
"INFORMATION"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"deprecated": true,
"description": "Deprecated alias for category. Prefer category='Battles' or category='CRIME'.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "event_category",
"parameter": "event_category"
}
},
"has_fatalities": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Set true to summarize only Stories linked to fatal Events. Implies has_events=true."
},
"story_category": {
"anyOf": [
{
"enum": [
"conflict_security",
"cameoplus_political",
"cameoplus_crime",
"cameoplus_economic",
"cameoplus_corporate",
"cameoplus_technology",
"cameoplus_infrastructure",
"cameoplus_environment",
"cameoplus_health",
"cameoplus_demographic",
"cameoplus_information",
"CONFLICT",
"CORPORATE",
"CRIME",
"DEMOGRAPHIC",
"ECONOMIC",
"ENVIRONMENT",
"HEALTH",
"INFORMATION",
"INFRASTRUCTURE",
"POLITICAL",
"TECHNOLOGY"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Legacy Story-cluster category such as 'conflict_security'. Prefer linked Event category/subcategory for product taxonomy filtering. Choices: get_parameter_options('summarize_stories', 'story_category').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "story_category",
"parameter": "story_category"
}
},
"event_categories": {
"anyOf": [
{
"type": "array",
"items": {
"enum": [
"Battles",
"Protests",
"Riots",
"Explosions/Remote violence",
"Violence against civilians",
"Strategic developments",
"POLITICAL",
"CRIME",
"ECONOMIC",
"CORPORATE",
"TECHNOLOGY",
"INFRASTRUCTURE",
"ENVIRONMENT",
"HEALTH",
"DEMOGRAPHIC",
"INFORMATION"
],
"type": "string"
}
},
{
"type": "null"
}
],
"default": null,
"deprecated": true,
"description": "Deprecated alias for categories. Prefer categories=[...].",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "event_category",
"parameter": "event_categories"
}
},
"article_count_max": {
"anyOf": [
{
"type": "integer",
"minimum": 0
},
{
"type": "null"
}
],
"default": null,
"description": "Maximum article count threshold for Story coverage."
},
"article_count_min": {
"anyOf": [
{
"type": "integer",
"minimum": 0
},
{
"type": "null"
}
],
"default": null,
"description": "Minimum article count threshold for Story coverage."
},
"civilian_targeting": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Set true to summarize only Stories linked to Conflict Events where ACLED civilian_targeting is populated."
},
"country_attribution": {
"anyOf": [
{
"enum": [
"primary",
"all"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "For group_by=country: primary preserves one primary country per Story; all counts each Story under every authoritative country attribution or linked Event location/actor origin, using the same country_match and other filters as the Stories list. Explicit geographic filters also restrict the emitted country buckets. Buckets overlap and must not be summed as a global total. Other groupings ignore this option.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "story_country_attribution",
"parameter": "country_attribution"
}
}
},
"x-gdelt-taxonomy": {
"category_values": [
"Battles",
"Protests",
"Riots",
"Explosions/Remote violence",
"Violence against civilians",
"Strategic developments",
"POLITICAL",
"CRIME",
"ECONOMIC",
"CORPORATE",
"TECHNOLOGY",
"INFRASTRUCTURE",
"ENVIRONMENT",
"HEALTH",
"DEMOGRAPHIC",
"INFORMATION"
],
"subcategory_rule": "Subcategory is validated against its parent category/categories. Use stable returned codes; legacy labels are accepted aliases. Unknown choices fail before billing. For unfamiliar labels, search get_event_taxonomy with a known category and the default page size.",
"deprecated_params": [
"event_category",
"event_categories",
"domain"
],
"subcategory_discovery": "Optional get_event_taxonomy(category=...) or get_parameter_options with parent_value scopes the choices; familiar valid filters need no lookup.",
"subcategory_category_params": [
"category",
"categories"
]
},
"additionalProperties": false,
"x-gdelt-errorRecovery": "Use category/categories for linked Event taxonomy. If validation fails, choose from compact accepted_values when present, otherwise use nearest_values or run a subcategory summary.",
"x-gdelt-deprecatedParams": [
"event_category",
"event_categories",
"domain"
],
"x-gdelt-subcategoryCategoryParams": [
"category",
"categories"
]
},
"outputSchema": {
"if": {
"required": [
"_mcp_projection"
]
},
"else": {
"type": "object",
"required": [
"success",
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Bucket value (e.g. the country / category)."
},
"metrics": {
"type": "object"
},
"group_by": {
"type": "string"
},
"fatalities": {
"type": [
"number",
"null"
]
},
"event_count": {
"type": "integer"
},
"metric_stats": {
"type": "object"
},
"article_count": {
"type": [
"integer",
"null"
]
}
},
"description": "One aggregate bucket. Counts: event_count, conflict_event_count, cameoplus_event_count, fatality_event_count, fatalities, article_count. Plus avg/min/max metric rollups and nested `metrics`/`metric_stats` (significance, goldstein, cameoplus, confidence, article_count, fatalities)."
}
},
"success": {
"type": "boolean"
},
"group_by": {
"type": "string"
},
"applied_filters": {
"type": "object"
}
},
"description": "Aggregate rollup grouped by `group_by` (one entry per bucket)."
},
"then": {
"type": "object",
"required": [
"_mcp_projection"
],
"properties": {
"data": {
"type": "array",
"description": "Compact records retain IDs, returned links, selected images, evidence and metrics where available; unknown values remain unknown."
},
"success": {
"type": "boolean"
},
"group_by": {
"type": "string"
},
"_mcp_projection": {
"type": "object",
"required": [
"mode"
],
"properties": {
"mode": {
"const": "compact"
},
"truncated": {
"type": "boolean"
}
},
"description": "Explicitly discloses omitted fields or shortened evidence."
},
"applied_filters": {
"type": "object"
}
}
},
"type": "object",
"description": "Full preserves the bounded API response. Compact preserves evidence, coverage, filters and pagination with explicit projection disclosure; neither fetches other pages."
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description98/100
Send an actual test through the saved Monitor email and/or webhook channels; requires Monitor-management access and the configured channel entitlement. This is a delivery test, not a scheduled check, and repeated calls can send repeated tests. Returns delivery outcomes for the configured channels; inspect channel failures before claiming delivery worked.
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
monitor_id
Organization Monitor UUID returned by create_monitor or list_monitors; select a Monitor in the connected organization. Choices: get_parameter_options('test_monitor_delivery', 'monitor_id').
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description96/100
Resolve a name, alias or acronym to cross-source identity candidates from public reporting, corporate/LEI, energy, restricted-party, finance and AI-compute reference data. Use for 'which entity is this?' before an ID-backed query or Monitor; search_entities instead measures actors appearing in a reporting window. Returns candidates, canonical entity_id where resolved, matching evidence, identifiers and sources availability. Unavailable source keys are DELETED from sources when WITHHELD by entitlement, not set false. An absent key means not searched; only a present false means checked with no match. Do not infer restricted-party status, source absence or news coverage from withheld results. country_match=strict checks source country association; include_unknown explicitly broadens it. Association is distinct from nationality, headquarters and reporting geography. Clarify consequential ambiguity. type=facility returns facility_id, distinct from the owner. holds_office selects a published role; holders remain persons. With universe=osint and holds_office=true, omit q to browse officials using sort=name and pagination.next_offset. osint returns publisher reference records that may have no entity_id; inspect resolved_in_spine and meta.lanes. universe=registry is the legal-entity LEI lane and does not accept holds_office. Source identity evidence is not a compliance determination or inference of private personal traits.
The description explains the capability, when to use it, and what to expect.
Inputs94/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
q
Canonical search text: a name, alias, or acronym. Required except when browsing public officials with universe=osint and holds_office=true. Until native non-Latin-script matching ships, use a common Romanized or English spelling for Cyrillic, Chinese, and other non-Latin names.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
sort
Use name for stable alphabetical public-official browsing with universe=osint and holds_office=true. Default when q is absent.
Clear enough to supply this argument.
offset
Number of records to skip before this page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
type
Optional identity type used to narrow ambiguous candidates. Conflicting linked types retain entity_type=entity and type_evidence; a filtered result includes a conflict only when the requested type is a published possibility. facility searches the existing facility directory and returns facility_id, not an invented entity ID. Source entitlements apply.
Clear enough to supply this argument.
limit
Number of records to return on this page; pagination describes how to continue.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
universe
Search all merged entities, news entities, reference entities, raw GLEIF registry records, or OSINT list and office-holder records. The registry and osint lanes return source records with nullable entity_id; they do not establish news coverage. Source entitlements apply.
Clear enough to supply this argument.
holds_office
Only politicians: entities that hold or have held a published public office (`sources.offices`), or on `universe=osint` only office-holder records. A ROLE filter, not a type — an office-holder is a `person`. Requires `can_use_offices` (403 PLAN_REQUIRED otherwise) and is not applicable to `universe=registry` (legal entities only; 400).
Clear enough to supply this argument.
country
Known country association from source records, not an assertion of headquarters, citizenship, or reporting location. Accepts country names, ISO-2 or ISO-3; comma-separate for OR. Use country_match=strict for candidates with known matching evidence. Choices: get_parameter_options('unified_entity_search', 'country').
Clear enough to supply this argument.
country_match
strict requires known matching source country association; include_unknown also returns candidates with no country evidence. Recommended requests explicitly send strict. Omission retains include_unknown compatibility.
Clear enough to supply this argument.
region
Geographic region whose member countries define the scope.
Clear enough to supply this argument.
continent
Continent whose member countries define the geographic scope.
Clear enough to supply this argument.
include_images
Retain source article image URLs on returned cards when available.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
{
"if": {
"required": [
"_mcp_projection"
]
},
"else": {
"type": "object",
"required": [
"success",
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"score": {
"type": [
"number",
"null"
],
"description": "Resolver match strength, not a probability or a coverage count."
},
"sources": {
"type": [
"object",
"array"
],
"description": "Facilities may list source identifiers. Entity maps preserve null for unknown coverage. Per-source availability booleans: news, sec, gem, sanctions, china, wiki, epoch, gov. ★ A GATED SOURCE THE CALLER'S PLAN DOES NOT INCLUDE IS DELETED FROM THIS MAP, NOT SET FALSE (sec, sanctions, china, epoch_ai, gov). An ABSENT key means WITHHELD — we did not look on this caller's behalf; only a key PRESENT and `false` means 'we looked and found none'. Reporting a missing key as no coverage is the measured defect this wording exists to prevent: a Professional caller was told RTX Corporation had no federal awards while it held 111 worth $44.3B."
},
"spine_id": {
"type": [
"string",
"null"
],
"description": "Canonical e_ entity ID when resolved; null when no canonical ID is available."
},
"entity_id": {
"type": [
"string",
"null"
],
"description": "Stable entity id (e_, wiki: or llm:) when available. Facility and unlinked source records have null; never use osint_ref or LEI as an entity Monitor id."
},
"image_url": {
"type": [
"string",
"null"
]
},
"match_type": {
"type": [
"string",
"null"
],
"description": "Lexical evidence such as exact_name, exact_alias, token_set or fuzzy_name."
},
"entity_type": {
"type": "string",
"description": "Canonical type, or neutral entity when linked source records conflict. Read type_evidence before treating that candidate as a person or organization."
},
"facility_id": {
"type": "string",
"description": "Canonical facility identity when type=facility, separate from its owner entity and nearby Events."
},
"identifiers": {
"type": "object",
"description": "Cross-source id map keyed by id_type (us_sec_cik, ticker, gem, epoch_org, aiddata_financier, ...) → list of values. Redacted the same way as `sources`: the id types behind a gated source the caller is not entitled to are DELETED, so a missing id_type means withheld, not absent."
},
"country_iso3": {
"type": "array",
"items": {
"type": "string"
},
"description": "Candidate ISO-3 countries used for disambiguation when known."
},
"coverage_30d": {
"type": [
"integer",
"null"
],
"description": "Measured recent Story coverage. Zero is measured absence; null or omitted coverage is unknown, never zero."
},
"match_reason": {
"type": [
"string",
"null"
]
},
"type_evidence": {
"type": "object",
"required": [
"status",
"candidate_types",
"records",
"note"
],
"properties": {
"note": {
"type": "string"
},
"status": {
"type": "string",
"const": "conflicting"
},
"records": {
"type": "array",
"items": {
"type": "object",
"required": [
"entity_id",
"source",
"entity_type"
],
"properties": {
"source": {
"enum": [
"reference",
"media",
"geg_wiki"
],
"type": "string"
},
"entity_id": {
"type": "string",
"description": "Supporting source record identity; it may be a merged-away reference ID."
},
"entity_type": {
"type": "string",
"description": "Unmodified type asserted by this source record."
}
},
"additionalProperties": false
}
},
"candidate_types": {
"type": "array",
"items": {
"enum": [
"person",
"organization",
"place"
],
"type": "string"
}
}
},
"description": "Optional unresolved type evidence. Type filters may retain the candidate only when the requested family is a published possibility; they do not resolve the disagreement or replace the stable identity.",
"additionalProperties": false
},
"wikipedia_url": {
"type": [
"string",
"null"
]
},
"entity_type_raw": {
"type": [
"string",
"null"
]
},
"country_evidence": {
"type": "object",
"description": "Basis and explanation of source country association; no known evidence has a null basis."
},
"source_universes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Which universes matched: media, geg_wiki, reference."
}
},
"description": "One real-world entity deduped across sources. `sources` is the per-source availability map and `identifiers` the cross-source join keys — the value a builder uses to bridge this entity across news / SEC filings / GEM energy / sanctions / China / Epoch AI. A gated source the caller is not entitled to is DELETED from both maps, so an absent key means WITHHELD, never absent."
}
},
"count": {
"type": "integer"
},
"query": {
"type": "string"
},
"success": {
"type": "boolean"
},
"pagination": {
"type": "object",
"properties": {
"limit": {
"type": "integer"
},
"offset": {
"type": "integer"
},
"has_more": {
"type": "boolean"
},
"next_offset": {
"type": [
"integer",
"null"
]
}
},
"description": "Present for alphabetical public-official browsing. Continue with next_offset; null means exhausted."
},
"applied_filters": {
"type": "object",
"description": "Echo of canonical query, universe, role and type filters."
}
},
"description": "Cross-source entity candidates deduped to one real-world entity per hit. `data` is the candidate list; default-universe `sources`/`identifiers` carry the cross-source join keys. Explicit osint/registry universes return publisher reference records, possibly without entity_id. Both maps are redacted per plan by DELETING gated keys, so absent means withheld, not absent."
},
"then": {
"type": "object",
"required": [
"_mcp_projection"
],
"properties": {
"data": {
"type": "array",
"description": "Compact records retain IDs, returned links, selected images, evidence and metrics where available; unknown values remain unknown."
},
"count": {
"type": "integer"
},
"query": {
"type": "string"
},
"success": {
"type": "boolean"
},
"pagination": {
"type": "object",
"properties": {
"limit": {
"type": "integer"
},
"offset": {
"type": "integer"
},
"has_more": {
"type": "boolean"
},
"next_offset": {
"type": [
"integer",
"null"
]
}
},
"description": "Present for alphabetical public-official browsing. Continue with next_offset; null means exhausted."
},
"_mcp_projection": {
"type": "object",
"required": [
"mode"
],
"properties": {
"mode": {
"const": "compact"
},
"truncated": {
"type": "boolean"
}
},
"description": "Explicitly discloses omitted fields or shortened evidence."
},
"applied_filters": {
"type": "object",
"description": "Echo of canonical query, universe, role and type filters."
}
}
},
"type": "object",
"description": "Full preserves the bounded API response. Compact preserves evidence, coverage, filters and pagination with explicit projection disclosure; neither fetches other pages."
}
Original tool metadata
{
"name": "unified_entity_search",
"title": "Resolve an entity identity",
"description": "Resolve a name, alias or acronym to cross-source identity candidates from public reporting, corporate/LEI, energy, restricted-party, finance and AI-compute reference data. Use for 'which entity is this?' before an ID-backed query or Monitor; search_entities instead measures actors appearing in a reporting window. Returns candidates, canonical entity_id where resolved, matching evidence, identifiers and sources availability. Unavailable source keys are DELETED from sources when WITHHELD by entitlement, not set false. An absent key means not searched; only a present false means checked with no match. Do not infer restricted-party status, source absence or news coverage from withheld results. country_match=strict checks source country association; include_unknown explicitly broadens it. Association is distinct from nationality, headquarters and reporting geography. Clarify consequential ambiguity. type=facility returns facility_id, distinct from the owner. holds_office selects a published role; holders remain persons. With universe=osint and holds_office=true, omit q to browse officials using sort=name and pagination.next_offset. osint returns publisher reference records that may have no entity_id; inspect resolved_in_spine and meta.lanes. universe=registry is the legal-entity LEI lane and does not accept holds_office. Source identity evidence is not a compliance determination or inference of private personal traits.",
"inputSchema": {
"type": "object",
"properties": {
"q": {
"anyOf": [
{
"type": "string",
"maxLength": 200,
"minLength": 1
},
{
"type": "null"
}
],
"default": null,
"description": "Canonical search text: a name, alias, or acronym. Required except when browsing public officials with universe=osint and holds_office=true. Until native non-Latin-script matching ships, use a common Romanized or English spelling for Cyrillic, Chinese, and other non-Latin names."
},
"sort": {
"anyOf": [
{
"type": "string",
"const": "name"
},
{
"type": "null"
}
],
"default": null,
"description": "Use name for stable alphabetical public-official browsing with universe=osint and holds_office=true. Default when q is absent.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"parameter": "sort"
}
},
"type": {
"anyOf": [
{
"enum": [
"person",
"organization",
"place",
"facility"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional identity type used to narrow ambiguous candidates. Conflicting linked types retain entity_type=entity and type_evidence; a filtered result includes a conflict only when the requested type is a published possibility. facility searches the existing facility directory and returns facility_id, not an invented entity ID. Source entitlements apply.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "search_entity_type",
"parameter": "type"
}
},
"limit": {
"type": "integer",
"default": 10,
"maximum": 50,
"minimum": 1,
"description": "Number of records to return on this page; pagination describes how to continue."
},
"offset": {
"anyOf": [
{
"type": "integer",
"minimum": 0
},
{
"type": "null"
}
],
"default": null,
"description": "Number of records to skip before this page."
},
"region": {
"anyOf": [
{
"enum": [
"Africa",
"Asia",
"Middle East",
"Northern Africa",
"Western Africa",
"Eastern Africa",
"Middle Africa",
"Southern Africa",
"Europe",
"Eastern Europe",
"South Asia",
"Southeast Asia",
"East Asia",
"Central Asia",
"North America",
"Central America",
"Caribbean",
"South America",
"Oceania"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Geographic region whose member countries define the scope.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "region",
"parameter": "region"
}
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Known country association from source records, not an assertion of headquarters, citizenship, or reporting location. Accepts country names, ISO-2 or ISO-3; comma-separate for OR. Use country_match=strict for candidates with known matching evidence. Choices: get_parameter_options('unified_entity_search', 'country').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "identifier",
"enum_id": "country",
"parameter": "country"
}
},
"universe": {
"anyOf": [
{
"enum": [
"all",
"news",
"reference",
"registry",
"osint"
],
"type": "string"
},
{
"type": "null"
}
],
"default": "all",
"description": "Search all merged entities, news entities, reference entities, raw GLEIF registry records, or OSINT list and office-holder records. The registry and osint lanes return source records with nullable entity_id; they do not establish news coverage. Source entitlements apply.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "search_universe",
"parameter": "universe"
}
},
"continent": {
"anyOf": [
{
"enum": [
"Africa",
"Asia",
"Europe",
"North America",
"South America",
"Oceania"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Continent whose member countries define the geographic scope.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "continent",
"parameter": "continent"
}
},
"holds_office": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Only politicians: entities that hold or have held a published public office (`sources.offices`), or on `universe=osint` only office-holder records. A ROLE filter, not a type — an office-holder is a `person`. Requires `can_use_offices` (403 PLAN_REQUIRED otherwise) and is not applicable to `universe=registry` (legal entities only; 400)."
},
"country_match": {
"anyOf": [
{
"enum": [
"strict",
"include_unknown"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "strict requires known matching source country association; include_unknown also returns candidates with no country evidence. Recommended requests explicitly send strict. Omission retains include_unknown compatibility.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "search_country_match",
"parameter": "country_match"
}
},
"response_mode": {
"enum": [
"compact",
"full"
],
"type": "string",
"default": "compact",
"description": "Compact chat projection or unchanged bounded full API response; neither fetches another page."
},
"include_images": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Retain source article image URLs on returned cards when available."
}
},
"additionalProperties": false
},
"outputSchema": {
"if": {
"required": [
"_mcp_projection"
]
},
"else": {
"type": "object",
"required": [
"success",
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"score": {
"type": [
"number",
"null"
],
"description": "Resolver match strength, not a probability or a coverage count."
},
"sources": {
"type": [
"object",
"array"
],
"description": "Facilities may list source identifiers. Entity maps preserve null for unknown coverage. Per-source availability booleans: news, sec, gem, sanctions, china, wiki, epoch, gov. ★ A GATED SOURCE THE CALLER'S PLAN DOES NOT INCLUDE IS DELETED FROM THIS MAP, NOT SET FALSE (sec, sanctions, china, epoch_ai, gov). An ABSENT key means WITHHELD — we did not look on this caller's behalf; only a key PRESENT and `false` means 'we looked and found none'. Reporting a missing key as no coverage is the measured defect this wording exists to prevent: a Professional caller was told RTX Corporation had no federal awards while it held 111 worth $44.3B."
},
"spine_id": {
"type": [
"string",
"null"
],
"description": "Canonical e_ entity ID when resolved; null when no canonical ID is available."
},
"entity_id": {
"type": [
"string",
"null"
],
"description": "Stable entity id (e_, wiki: or llm:) when available. Facility and unlinked source records have null; never use osint_ref or LEI as an entity Monitor id."
},
"image_url": {
"type": [
"string",
"null"
]
},
"match_type": {
"type": [
"string",
"null"
],
"description": "Lexical evidence such as exact_name, exact_alias, token_set or fuzzy_name."
},
"entity_type": {
"type": "string",
"description": "Canonical type, or neutral entity when linked source records conflict. Read type_evidence before treating that candidate as a person or organization."
},
"facility_id": {
"type": "string",
"description": "Canonical facility identity when type=facility, separate from its owner entity and nearby Events."
},
"identifiers": {
"type": "object",
"description": "Cross-source id map keyed by id_type (us_sec_cik, ticker, gem, epoch_org, aiddata_financier, ...) → list of values. Redacted the same way as `sources`: the id types behind a gated source the caller is not entitled to are DELETED, so a missing id_type means withheld, not absent."
},
"country_iso3": {
"type": "array",
"items": {
"type": "string"
},
"description": "Candidate ISO-3 countries used for disambiguation when known."
},
"coverage_30d": {
"type": [
"integer",
"null"
],
"description": "Measured recent Story coverage. Zero is measured absence; null or omitted coverage is unknown, never zero."
},
"match_reason": {
"type": [
"string",
"null"
]
},
"type_evidence": {
"type": "object",
"required": [
"status",
"candidate_types",
"records",
"note"
],
"properties": {
"note": {
"type": "string"
},
"status": {
"type": "string",
"const": "conflicting"
},
"records": {
"type": "array",
"items": {
"type": "object",
"required": [
"entity_id",
"source",
"entity_type"
],
"properties": {
"source": {
"enum": [
"reference",
"media",
"geg_wiki"
],
"type": "string"
},
"entity_id": {
"type": "string",
"description": "Supporting source record identity; it may be a merged-away reference ID."
},
"entity_type": {
"type": "string",
"description": "Unmodified type asserted by this source record."
}
},
"additionalProperties": false
}
},
"candidate_types": {
"type": "array",
"items": {
"enum": [
"person",
"organization",
"place"
],
"type": "string"
}
}
},
"description": "Optional unresolved type evidence. Type filters may retain the candidate only when the requested family is a published possibility; they do not resolve the disagreement or replace the stable identity.",
"additionalProperties": false
},
"wikipedia_url": {
"type": [
"string",
"null"
]
},
"entity_type_raw": {
"type": [
"string",
"null"
]
},
"country_evidence": {
"type": "object",
"description": "Basis and explanation of source country association; no known evidence has a null basis."
},
"source_universes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Which universes matched: media, geg_wiki, reference."
}
},
"description": "One real-world entity deduped across sources. `sources` is the per-source availability map and `identifiers` the cross-source join keys — the value a builder uses to bridge this entity across news / SEC filings / GEM energy / sanctions / China / Epoch AI. A gated source the caller is not entitled to is DELETED from both maps, so an absent key means WITHHELD, never absent."
}
},
"count": {
"type": "integer"
},
"query": {
"type": "string"
},
"success": {
"type": "boolean"
},
"pagination": {
"type": "object",
"properties": {
"limit": {
"type": "integer"
},
"offset": {
"type": "integer"
},
"has_more": {
"type": "boolean"
},
"next_offset": {
"type": [
"integer",
"null"
]
}
},
"description": "Present for alphabetical public-official browsing. Continue with next_offset; null means exhausted."
},
"applied_filters": {
"type": "object",
"description": "Echo of canonical query, universe, role and type filters."
}
},
"description": "Cross-source entity candidates deduped to one real-world entity per hit. `data` is the candidate list; default-universe `sources`/`identifiers` carry the cross-source join keys. Explicit osint/registry universes return publisher reference records, possibly without entity_id. Both maps are redacted per plan by DELETING gated keys, so absent means withheld, not absent."
},
"then": {
"type": "object",
"required": [
"_mcp_projection"
],
"properties": {
"data": {
"type": "array",
"description": "Compact records retain IDs, returned links, selected images, evidence and metrics where available; unknown values remain unknown."
},
"count": {
"type": "integer"
},
"query": {
"type": "string"
},
"success": {
"type": "boolean"
},
"pagination": {
"type": "object",
"properties": {
"limit": {
"type": "integer"
},
"offset": {
"type": "integer"
},
"has_more": {
"type": "boolean"
},
"next_offset": {
"type": [
"integer",
"null"
]
}
},
"description": "Present for alphabetical public-official browsing. Continue with next_offset; null means exhausted."
},
"_mcp_projection": {
"type": "object",
"required": [
"mode"
],
"properties": {
"mode": {
"const": "compact"
},
"truncated": {
"type": "boolean"
}
},
"description": "Explicitly discloses omitted fields or shortened evidence."
},
"applied_filters": {
"type": "object",
"description": "Echo of canonical query, universe, role and type filters."
}
}
},
"type": "object",
"description": "Full preserves the bounded API response. Compact preserves evidence, coverage, filters and pagination with explicit projection disclosure; neither fetches other pages."
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description98/100
Persist explicit changes to the organization Monitor name, subject, criteria, schedule, delivery or enabled state; requires Monitor-management access. Omitted fields retain their values and REST revalidates the result against current access. The changes affect future checks and delivery. Returns the updated Monitor and any one-time webhook_signing_secret.
The description explains the capability, when to use it, and what to expect.
Inputs92/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
monitor_id
Organization Monitor UUID returned by create_monitor or list_monitors; select a Monitor in the connected organization. Choices: get_parameter_options('update_monitor', 'monitor_id').
Clear enough to supply this argument.
patch
Canonical partial REST Monitor request. Accepted top-level keys: name, description (null clears it), subject, criteria, trigger, schedule, delivery, rotate_webhook_secret, enabled. Delivery uses {email: boolean, webhook_url: string|null}; get_monitor instead returns webhook.endpoint and health, which must not be copied into a PATCH. Omit unchanged fields. Choices: get_parameter_options('update_monitor', 'patch').
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description92/100
Persist creator-only changes to a saved v1 query or typed v2 investigation/request. Uses create_saved_query recipe shapes; nested objects are replaced, not deep-merged. The final recipe is revalidated by REST. opened=true records reopening; omitted fields retain their values. Returns the saved data, validated href, incompatibility and can_edit; saving does not execute the query.
The description explains the capability, when to use it, and what to expect.
Inputs86/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
query_id
Saved query UUID returned by list_saved_queries or create_saved_query.
Clear enough to supply this argument.
patch
Explicit changes to title, params, time_spec, display, pinned, visibility, or contract_version and investigation/request metadata. Supply complete replacement nested objects; clear the other kind with null when switching. opened=true records reopening. Omitted fields are retained; REST revalidates the result. Choices: get_parameter_options('update_saved_query', 'patch').
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description93/100
When the user asks to prepare, edit or review a Monitor, call this read-only tool to open its interactive form; do not substitute a code-block template. Country/category and email/webhook controls are provided. Use countries, cameoplus_domains/conflict_categories and daily_hour from the schema; omit enabled (Preview is always unsaved). Pass validated direct preview_monitor parameters; never saves or sends. Returns monitor_form with draft, scope and preview receipt. Preview consumes metered usage when admitted; its receipt is an unsaved test, never a completed scheduled checkpoint. Do not claim rendering without client evidence. Wait for confirmation before creation; use validated text only if rendering is unavailable.
The description explains the capability, when to use it, and what to expect.
Inputs96/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
name
Short name for the Monitor being previewed.
Clear enough to supply this argument.
description
Human-readable purpose or instructions associated with the Monitor draft.
Clear enough to supply this argument.
subject_type
What the Monitor watches. Connected subjects follow selected entities or facilities; category subjects watch Event types without geography and require a taxonomy scope. Query subjects use the selected endpoint filters.
Clear enough to supply this argument.
search
Semantic Event/Story content to match. Required for topic Monitors. This is not entity-name resolution; use unified_entity_search first.
Clear enough to supply this argument.
entity_ids
Resolved entity IDs from unified_entity_search. Select the intended candidates and reuse their e_, wiki: or llm: IDs; never pass bare names. Choices: get_parameter_options('preview_monitor', 'entity_ids').
Clear enough to supply this argument.
facility_id
Canonical facility identifier returned by facilities_search or unified_entity_search; reuse the selected facility ID. Choices: get_parameter_options('preview_monitor', 'facility_id').
Clear enough to supply this argument.
target_type
For connected Monitors: entity or facility. Prefer this subject for company or asset watches.
Latitude in decimal degrees, north-positive, for the place Monitor center; used with longitude.
Clear enough to supply this argument.
longitude
Longitude in decimal degrees, east-positive, for the place Monitor center; used with latitude.
Clear enough to supply this argument.
radius_km
Distance in kilometres around a facility or point target. Omission preserves the REST radius of 25 km; omit for query subjects.
Clear enough to supply this argument.
data
Whether legacy subjects match Events, Stories or both. Omission preserves events_and_stories; omit for query subjects, whose endpoint determines the data.
Clear enough to supply this argument.
cameoplus_domains
Canonical CAMEO+ domains.
Clear enough to supply this argument.
cameoplus_subcategories
CAMEO+ Event codes within the selected cameoplus_domains; use the corresponding parent domains. Choices: get_parameter_options('preview_monitor', 'cameoplus_subcategories').
Clear enough to supply this argument.
conflict_categories
Conflict Event types to watch, such as Battles; scope by what happened rather than Story topic.
Clear enough to supply this argument.
conflict_subcategories
Conflict sub-event types within the selected conflict_categories; use the corresponding parent categories. Choices: get_parameter_options('preview_monitor', 'conflict_subcategories').
Clear enough to supply this argument.
story_categories
Story-level topics to watch; distinct from the linked Events taxonomy.
Clear enough to supply this argument.
fatalities_only
Restrict compatible conflict Events to records with fatalities.
Clear enough to supply this argument.
cadence
How often the Monitor checks for newly matching records, subject to the connected account entitlement.
Clear enough to supply this argument.
timezone
IANA timezone name used to interpret the daily schedule, such as America/New_York. Choices: get_parameter_options('preview_monitor', 'timezone').
Clear enough to supply this argument.
daily_hour
Hour of the daily check in the selected timezone; retained but ignored for hourly cadence.
Clear enough to supply this argument.
email
Retained email-delivery setting for the draft. Preview never sends email and needs no delivery channel.
Clear enough to supply this argument.
webhook_url
Draft webhook destination. Preview retains it but never contacts it and does not require it.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
query_endpoint
Public read endpoint whose saved filters define a query Monitor; selects the endpoint-specific filter grammar.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
query_params
Saved filters for query_endpoint. Resolve names first and reuse selected IDs. Omit fixed dates and pagination because scheduled execution supplies its own window and page bounds. Choices: get_parameter_options('preview_monitor', 'query_params').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
source_request › anyOf › 0 › endpoint
Public read endpoint that produced the original result. Retained as source context; never executed by the schedule.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
source_request › anyOf › 0 › params
Parameters of the original request, including its discovery dates or pagination. Retained for explanation, independently of the scheduled filters.
Clear enough to supply this argument.
monitor_id
Organization Monitor UUID returned by create_monitor or list_monitors; select a Monitor in the connected organization. Choices: get_parameter_options('preview_monitor', 'monitor_id').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
history_days
Setup history: 7 days by default, or 30. Preview never establishes a scheduled checkpoint or sends delivery; incomplete history remains explicit.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
{
"type": "object",
"required": [
"monitor_form"
],
"properties": {
"monitor_form": {
"type": "object",
"required": [
"version",
"saved",
"status",
"draft",
"scope",
"preview_receipt"
],
"properties": {
"draft": {
"type": "object",
"description": "Validated create_monitor arguments; the webhook destination is omitted."
},
"saved": {
"const": false,
"description": "Preparation never creates or changes a saved Monitor."
},
"scope": {
"type": "object",
"description": "Readable subject and filter interpretation for review."
},
"status": {
"type": "string",
"description": "Preparation status."
},
"version": {
"const": 1,
"description": "Portable Monitor-form data version."
},
"preview_receipt": {
"type": "object",
"description": "Observed match/coverage receipt from the metered Preview; a Preview is not a saved Monitor or scheduled checkpoint."
}
},
"description": "Validated unsaved draft, readable scope and match receipt. Webhook URL is omitted; the user may enter it privately in the form."
}
},
"description": "Read-only Monitor preparation. Includes the bounded Preview response and portable monitor_form data for the component or text fallback. Rendering remains client-dependent."
}
Original tool metadata
{
"name": "gdelt_cloud_monitor_form",
"title": "Review Monitor draft",
"description": "When the user asks to prepare, edit or review a Monitor, call this read-only tool to open its interactive form; do not substitute a code-block template. Country/category and email/webhook controls are provided. Use countries, cameoplus_domains/conflict_categories and daily_hour from the schema; omit enabled (Preview is always unsaved). Pass validated direct preview_monitor parameters; never saves or sends. Returns monitor_form with draft, scope and preview receipt. Preview consumes metered usage when admitted; its receipt is an unsaved test, never a completed scheduled checkpoint. Do not claim rendering without client evidence. Wait for confirmation before creation; use validated text only if rendering is unavailable.",
"inputSchema": {
"type": "object",
"required": [
"name",
"subject_type"
],
"properties": {
"data": {
"anyOf": [
{
"enum": [
"events",
"stories",
"events_and_stories"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether legacy subjects match Events, Stories or both. Omission preserves events_and_stories; omit for query subjects, whose endpoint determines the data.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"parameter": "data"
}
},
"name": {
"type": "string",
"description": "Short name for the Monitor being previewed."
},
"email": {
"type": "boolean",
"default": false,
"description": "Retained email-delivery setting for the draft. Preview never sends email and needs no delivery channel."
},
"admin1": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Admin-1 subject/refinement. Choices: get_parameter_options('preview_monitor', 'admin1').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "observed",
"enum_id": "admin1",
"parameter": "admin1"
}
},
"region": {
"anyOf": [
{
"enum": [
"Africa",
"Asia",
"Middle East",
"Northern Africa",
"Western Africa",
"Eastern Africa",
"Middle Africa",
"Southern Africa",
"Europe",
"Eastern Europe",
"South Asia",
"Southeast Asia",
"East Asia",
"Central Asia",
"North America",
"Central America",
"Caribbean",
"South America",
"Oceania"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Geographic region for a geography subject, or a geographic refinement of another Monitor subject.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "region",
"parameter": "region"
}
},
"search": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Semantic Event/Story content to match. Required for topic Monitors. This is not entity-name resolution; use unified_entity_search first."
},
"cadence": {
"enum": [
"hourly",
"daily"
],
"type": "string",
"default": "daily",
"description": "How often the Monitor checks for newly matching records, subject to the connected account entitlement.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"parameter": "cadence"
}
},
"latitude": {
"anyOf": [
{
"type": "number",
"maximum": 90,
"minimum": -90
},
{
"type": "null"
}
],
"default": null,
"description": "Latitude in decimal degrees, north-positive, for the place Monitor center; used with longitude."
},
"timezone": {
"type": "string",
"default": "UTC",
"description": "IANA timezone name used to interpret the daily schedule, such as America/New_York. Choices: get_parameter_options('preview_monitor', 'timezone').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "identifier",
"parameter": "timezone"
}
},
"continent": {
"anyOf": [
{
"enum": [
"Africa",
"Asia",
"Europe",
"North America",
"South America",
"Oceania"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Continent for a geography subject, or a geographic refinement of another Monitor subject.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "continent",
"parameter": "continent"
}
},
"countries": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"default": null,
"description": "ISO-3 countries for a geography Monitor, or geographic refinements of another subject. Choices: get_parameter_options('preview_monitor', 'countries').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "identifier",
"enum_id": "country",
"parameter": "countries"
}
},
"longitude": {
"anyOf": [
{
"type": "number",
"maximum": 180,
"minimum": -180
},
{
"type": "null"
}
],
"default": null,
"description": "Longitude in decimal degrees, east-positive, for the place Monitor center; used with latitude."
},
"radius_km": {
"anyOf": [
{
"type": "number",
"maximum": 1000,
"exclusiveMinimum": 0
},
{
"type": "null"
}
],
"default": null,
"description": "Distance in kilometres around a facility or point target. Omission preserves the REST radius of 25 km; omit for query subjects."
},
"daily_hour": {
"type": "integer",
"default": 8,
"maximum": 23,
"minimum": 0,
"description": "Hour of the daily check in the selected timezone; retained but ignored for hourly cadence."
},
"entity_ids": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"default": null,
"description": "Resolved entity IDs from unified_entity_search. Select the intended candidates and reuse their e_, wiki: or llm: IDs; never pass bare names. Choices: get_parameter_options('preview_monitor', 'entity_ids').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "identifier",
"enum_id": "entity_handle",
"parameter": "entity_ids"
}
},
"monitor_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Organization Monitor UUID returned by create_monitor or list_monitors; select a Monitor in the connected organization. Choices: get_parameter_options('preview_monitor', 'monitor_id').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "identifier",
"parameter": "monitor_id"
}
},
"target_ids": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
},
"maxItems": 25,
"minItems": 1
},
{
"type": "null"
}
],
"default": null,
"description": "Resolved selected entity/facility IDs. Selected-item limit is account-dependent; clarify consequential identity ambiguity. Choices: get_parameter_options('preview_monitor', 'target_ids').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "identifier",
"parameter": "target_ids"
}
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Human-readable purpose or instructions associated with the Monitor draft."
},
"facility_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Canonical facility identifier returned by facilities_search or unified_entity_search; reuse the selected facility ID. Choices: get_parameter_options('preview_monitor', 'facility_id').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "identifier",
"parameter": "facility_id"
}
},
"search_mode": {
"anyOf": [
{
"enum": [
"semantic",
"lexical"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Content matching mode; omission preserves the API default.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"parameter": "search_mode"
}
},
"target_type": {
"anyOf": [
{
"enum": [
"entity",
"facility"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "For connected Monitors: entity or facility. Prefer this subject for company or asset watches.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"parameter": "target_type"
}
},
"webhook_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Draft webhook destination. Preview retains it but never contacts it and does not require it."
},
"history_days": {
"enum": [
7,
30
],
"type": "integer",
"default": 7,
"description": "Setup history: 7 days by default, or 30. Preview never establishes a scheduled checkpoint or sends delivery; incomplete history remains explicit.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"parameter": "history_days"
}
},
"query_params": {
"anyOf": [
{
"type": "object",
"additionalProperties": {
"type": "string"
}
},
{
"type": "null"
}
],
"default": null,
"description": "Saved filters for query_endpoint. Resolve names first and reuse selected IDs. Omit fixed dates and pagination because scheduled execution supplies its own window and page bounds. Choices: get_parameter_options('preview_monitor', 'query_params').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "parameters",
"parameter": "query_params",
"parent_parameter": "query_endpoint"
}
},
"subject_type": {
"enum": [
"topic",
"entity",
"facility",
"connected",
"geography",
"place",
"category",
"query"
],
"type": "string",
"description": "What the Monitor watches. Connected subjects follow selected entities or facilities; category subjects watch Event types without geography and require a taxonomy scope. Query subjects use the selected endpoint filters.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"parameter": "subject_type"
}
},
"related_scope": {
"anyOf": [
{
"enum": [
"direct",
"connected"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Connected scope includes related records; direct selects the roots only. Omission preserves connected for connected subjects.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"parameter": "related_scope"
}
},
"query_endpoint": {
"anyOf": [
{
"enum": [
"/api/v2/events",
"/api/v2/stories",
"/api/v2/entities",
"/api/v2/activity",
"/api/v2/situations/{story_id}/editions"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Public read endpoint whose saved filters define a query Monitor; selects the endpoint-specific filter grammar.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "monitor-query-endpoint",
"parameter": "query_endpoint"
}
},
"source_request": {
"anyOf": [
{
"type": "object",
"required": [
"endpoint",
"params"
],
"properties": {
"params": {
"type": "object",
"description": "Parameters of the original request, including its discovery dates or pagination. Retained for explanation, independently of the scheduled filters.",
"additionalProperties": {
"type": "string"
}
},
"endpoint": {
"enum": [
"/api/v2/events",
"/api/v2/stories",
"/api/v2/entities",
"/api/v2/activity",
"/api/v2/situations/{story_id}/editions"
],
"type": "string",
"description": "Public read endpoint that produced the original result. Retained as source context; never executed by the schedule."
}
}
},
{
"type": "null"
}
],
"default": null,
"description": "Original executed endpoint and params, including discovery dates/pagination. Retained for explanation and never executed by the schedule. Choices: get_parameter_options('preview_monitor', 'source_request').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "parameters",
"parameter": "source_request"
}
},
"source_updates": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"default": null,
"description": "Connected source update groups. Discover exact choices through get_parameter_options. Omit for source defaults; [] disables source updates.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"parameter": "source_updates"
}
},
"fatalities_only": {
"type": "boolean",
"default": false,
"description": "Restrict compatible conflict Events to records with fatalities."
},
"nearby_radius_km": {
"anyOf": [
{
"type": "number",
"maximum": 1000,
"exclusiveMinimum": 0
},
{
"type": "null"
}
],
"default": null,
"description": "Explicit opt-in nearby Events for connected facilities. Omission does not add proximity; never infer an outage from nearby news."
},
"story_categories": {
"anyOf": [
{
"type": "array",
"items": {
"enum": [
"conflict_security",
"cameoplus_political",
"cameoplus_crime",
"cameoplus_economic",
"cameoplus_corporate",
"cameoplus_technology",
"cameoplus_infrastructure",
"cameoplus_environment",
"cameoplus_health",
"cameoplus_demographic",
"cameoplus_information",
"CONFLICT",
"CORPORATE",
"CRIME",
"DEMOGRAPHIC",
"ECONOMIC",
"ENVIRONMENT",
"HEALTH",
"INFORMATION",
"INFRASTRUCTURE",
"POLITICAL",
"TECHNOLOGY"
],
"type": "string"
}
},
{
"type": "null"
}
],
"default": null,
"description": "Story-level topics to watch; distinct from the linked Events taxonomy.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "story_category",
"parameter": "story_categories"
}
},
"cameoplus_domains": {
"anyOf": [
{
"type": "array",
"items": {
"enum": [
"POLITICAL",
"CRIME",
"ECONOMIC",
"CORPORATE",
"TECHNOLOGY",
"INFRASTRUCTURE",
"ENVIRONMENT",
"HEALTH",
"DEMOGRAPHIC",
"INFORMATION"
],
"type": "string"
}
},
{
"type": "null"
}
],
"default": null,
"description": "Canonical CAMEO+ domains.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "cameoplus_domain",
"parameter": "cameoplus_domains"
}
},
"conflict_categories": {
"anyOf": [
{
"type": "array",
"items": {
"enum": [
"Battles",
"Protests",
"Riots",
"Explosions/Remote violence",
"Violence against civilians",
"Strategic developments"
],
"type": "string"
}
},
{
"type": "null"
}
],
"default": null,
"description": "Conflict Event types to watch, such as Battles; scope by what happened rather than Story topic.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"parameter": "conflict_categories"
}
},
"conflict_subcategories": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"default": null,
"description": "Conflict sub-event types within the selected conflict_categories; use the corresponding parent categories. Choices: get_parameter_options('preview_monitor', 'conflict_subcategories').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "event_subcategory",
"parameter": "conflict_subcategories",
"parent_parameter": "conflict_categories"
}
},
"cameoplus_subcategories": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"default": null,
"description": "CAMEO+ Event codes within the selected cameoplus_domains; use the corresponding parent domains. Choices: get_parameter_options('preview_monitor', 'cameoplus_subcategories').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "event_subcategory",
"parameter": "cameoplus_subcategories",
"parent_parameter": "cameoplus_domains"
}
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"required": [
"monitor_form"
],
"properties": {
"monitor_form": {
"type": "object",
"required": [
"version",
"saved",
"status",
"draft",
"scope",
"preview_receipt"
],
"properties": {
"draft": {
"type": "object",
"description": "Validated create_monitor arguments; the webhook destination is omitted."
},
"saved": {
"const": false,
"description": "Preparation never creates or changes a saved Monitor."
},
"scope": {
"type": "object",
"description": "Readable subject and filter interpretation for review."
},
"status": {
"type": "string",
"description": "Preparation status."
},
"version": {
"const": 1,
"description": "Portable Monitor-form data version."
},
"preview_receipt": {
"type": "object",
"description": "Observed match/coverage receipt from the metered Preview; a Preview is not a saved Monitor or scheduled checkpoint."
}
},
"description": "Validated unsaved draft, readable scope and match receipt. Webhook URL is omitted; the user may enter it privately in the form."
}
},
"description": "Read-only Monitor preparation. Includes the bounded Preview response and portable monitor_form data for the component or text fallback. Rendering remains client-dependent."
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description97/100
Pivot from a GEM Entity ID to every asset that entity owns, operates, or parents — across all trackers in one call. Returns capacity rollup plus the full asset list. Use for portfolio exposure questions ("what does Vattenfall own?", "which plants does ExxonMobil operate?"). To find the entity_id, first call energy_search_owners for a clean ownership-registry match, or call energy_search_assets with owner_search='<name>' to find candidates from asset cards. The result list spans coal/oil/gas/nuclear/renewables; combine with country or region to scope the portfolio.
The description explains the capability, when to use it, and what to expect.
Inputs87/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
owner_entity_id
Owner identifier returned as entity_id by energy_search_owners; filters the portfolio before aggregation. Choices: get_parameter_options('energy_assets_by_owner', 'owner_entity_id').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
country
One or more country filters to scope the entity's portfolio. For a single country pass a one-element list. Choices: get_parameter_options('energy_assets_by_owner', 'country').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
region
Geographic region of assets in the selected owner portfolio, expanded to its member countries.
Clear enough to supply this argument.
continent
Continent of assets in the selected owner portfolio, expanded to its member countries.
Clear enough to supply this argument.
operating_only
Shorthand for status='operating'.
Clear enough to supply this argument.
sort
Order of assets in the selected owner portfolio, such as highest capacity first.
Clear enough to supply this argument.
limit
Number of asset cards per page. Page with cursor for deeper sets; use energy_summarize_assets when only counts or aggregates are needed.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description92/100
Read Global Energy Monitor LNG and gas-power project financing and procurement observations. Use to examine reported financiers, contractors or purchasers, source evidence and unresolved parties. Filter by participant entity/role, country, project-name substring q and collection (lng_terminals or gas_power_plants); follow cursor pagination. Preserve original units and dated values; repeated project totals must not be summed across financiers. This reads source records and does not arrange financing or payments.
The description explains the capability, when to use it, and what to expect.
Inputs93/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
entity
Participant entity: spine id, news id, Wikipedia URL or resolved name. Unresolved names return 404. Choices: get_parameter_options('energy_finance', 'entity').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
participant_role
Source-supported role of the selected entity in the record; distinguish owners, operators, financiers and users. A hardware ownership role does not establish ownership of a building. Choices: get_parameter_options('energy_finance', 'participant_role').
Clear enough to supply this argument.
collection
Source collection identifier returned by these observations or the coverage catalog; narrows to that dataset collection. Choices: get_parameter_options('energy_finance', 'collection').
The title clearly communicates the tool’s action and subject. Keep it concise.
Description96/100
Fetch one Energy Data asset by tracker + gem_id for full detail after energy_search_assets. Returns the complete record including all per-tracker fields (combustion technology / mining method / reactor type / capacity factor / methane emissions / route geometry / etc.), the full ownership chain with entity IDs and stake percentages, native capacity in original units, secondary country (for binational hydropower and pipelines), and the GEM Wiki URL. Additional source-record fields are included where available.
The description explains the capability, when to use it, and what to expect.
Inputs89/100
Explain what happens when this optional value is omitted.
gem_id
GEM asset identifier returned by energy_search_assets; reuse the selected asset gem_id. Choices: get_parameter_options('energy_get_asset', 'gem_id').
Clear enough to supply this argument.
tracker
Source tracker identifying the asset class; use trackers returned by energy_search_assets.
Explain what happens when this optional value is omitted.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description97/100
Fetch one GEM ownership entity by entity_id, including registration/headquarters metadata, parent GEM entities, external IDs, and a portfolio summary across energy assets. Optional include_exposure=true requests the admin-gated risk/exposure preview summary for that owner. Returns data owner identity, parent links, external identifiers and the portfolio summary. Retain per-tracker units; an optional exposure block is a separately gated preview.
The description explains the capability, when to use it, and what to expect.
Inputs91/100
Input documentation gives an agent enough context to populate the arguments.
entity_id
Owner identifier returned as entity_id by energy_search_owners. Choices: get_parameter_options('energy_get_owner', 'entity_id').
Clear enough to supply this argument.
include_exposure
Include admin-gated exposure summaries from the risk/exposure preview. Non-admin callers receive a 403 from the API.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description98/100
Search native Global Energy Monitor records for technology and ownership detail. For country-context asset lists or nearby infrastructure, prefer facilities_search with source=[gem], which returns public GDELT Cloud facility links. This specialist spans v2 trackers: coal plants, coal mines, coal terminals, oil & gas plants, oil & gas extraction fields, LNG terminals, nuclear, geothermal, bioenergy, hydropower, solar, and wind. Geography filters (country, region, continent) use the same ISO-3 expansion as search_events, so cross-product analyses ('events near energy assets in region X') stay consistent. Filter by status (operating/proposed/retired/etc.), fuel, capacity range (MW for power generation), start year, owner substring or GEM Entity ID, geographic bbox or radius proximity ('near'), and asset name. Returns clean asset cards with capacity, location, ownership chain (owners/operators/parents with stake percentages), GEM Wiki URL, and a detail_url for drilldown via energy_get_asset. GEM links credit the source; they do not replace facility-page citations.
The description explains the capability, when to use it, and what to expect.
Inputs94/100
Resolve the mismatch between this description and its schema constraints.
tracker
Source tracker identifying the asset class; use trackers returned by energy_search_assets.
Resolve the mismatch between this description and its schema constraints.
country
One or more plain-English country names or ISO-3 codes; matches the asset's primary or secondary country. For a single country pass a one-element list: country=['United States']. Choices: get_parameter_options('energy_search_assets', 'country').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
region
One plain-English region (Middle East, Europe, South Asia, …). Expanded to its ISO-3 country list and applied the same way as `country`, so cross-product analyses use a consistent country set.
Clear enough to supply this argument.
continent
One plain-English continent (Asia, Europe, Africa, North America, South America, Oceania). Expanded to its ISO-3 country list and applied the same way as `country`.
Clear enough to supply this argument.
status
One or more GEM status values. 'operating' is the most common; transition/planning analyses pair it with 'construction', 'pre-construction', 'permitted', 'announced', 'proposed' (planned) versus 'retired', 'cancelled', 'shelved', 'mothballed' (defunct).
Clear enough to supply this argument.
operating_only
Shorthand for status=['operating']. Use this when filtering for currently operating assets only — overrides any explicit status.
Clear enough to supply this argument.
tier
Tier discriminator within a tracker. 'main' (default for most), 'sub_threshold' (oil_gas_plants), 'below_threshold' (wind, hydropower), 'utility' (solar 1MW+), 'distributed' (solar <1MW), 'closed' (coal_mines closed sheet). Choices: get_parameter_options('energy_search_assets', 'tier').
Clear enough to supply this argument.
fuel
Normalized fuel class of the selected asset. Use the values in this schema; native source fuel labels are returned evidence, not accepted filter values.
Clear enough to supply this argument.
capacity_mw_min
Minimum capacity in MW. Only valid for power-generation trackers (coal_plants, oil_gas_plants, nuclear, geothermal, bioenergy, hydropower, solar, wind). Other trackers report capacity in Mtpa/Mt/Bcm-y — use the native capacity_value column via get_asset for those.
Clear enough to supply this argument.
capacity_mw_max
Maximum capacity in MW; see capacity_mw_min.
Clear enough to supply this argument.
start_year_min
Earliest start_year (asset became operational or planned).
Clear enough to supply this argument.
start_year_max
Latest start_year.
Clear enough to supply this argument.
owner_search
Substring match against the raw owners string (case-insensitive). Use this for fuzzy ownership searches like 'ExxonMobil' or 'Vattenfall'. For exact ownership lookups, use owner_entity_id.
Clear enough to supply this argument.
owner_entity_id
Owner identifier returned as entity_id by energy_search_owners; filters the portfolio before aggregation. Choices: get_parameter_options('energy_search_assets', 'owner_entity_id').
Clear enough to supply this argument.
bbox
Geographic viewport: 'lat_min,lon_min,lat_max,lon_max'. Returns assets with lat/lon inside the bounding box.
Clear enough to supply this argument.
near
Proximity query: 'lat,lon,radius_km'. Returns assets within the radius. Use for 'energy assets near event location'.
Clear enough to supply this argument.
search
Substring match against asset name (case-insensitive). Use for project lookups like 'Itaipu' or 'Sabine Pass'.
Clear enough to supply this argument.
asset_class
'fixed' for stationary infrastructure; 'mobile' for LNG carriers and other vessels; 'all' to include both.
Clear enough to supply this argument.
sort
'capacity_desc' for largest first; 'capacity_mw' is accepted as a backward-compatible alias for 'capacity_desc'; 'start_year_desc' for newest; 'recent' for most-recently-updated; 'name' for alphabetical.
Clear enough to supply this argument.
limit
Number of asset cards per page. Page with cursor for deeper sets; use energy_summarize_assets when only counts or aggregates are needed.
Clear enough to supply this argument.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description92/100
Search GDELT Cloud's indexed public energy-ownership records, attributed to Global Energy Monitor, by owner name, abbreviation, GEM Entity ID, external IDs, country, entity type, or public-listing status. Use this before energy_assets_by_owner when the user's question names a company, ministry, state owner, person, or investment vehicle and you need the canonical GEM Entity ID.
The description explains the capability, when to use it, and what to expect.
Inputs85/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
q
Search GEM ownership entities by name, abbreviation, entity ID, or external ID. Use this before energy_assets_by_owner when the owner ID is unknown.
Clear enough to supply this argument.
entity_id
Owner identifier returned as entity_id by energy_search_owners. Choices: get_parameter_options('energy_search_owners', 'entity_id').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
country
One or more country names or ISO-3 codes; matches registration or headquarters country. Choices: get_parameter_options('energy_search_owners', 'country').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
region
Optional region filter over registration or headquarters country.
Clear enough to supply this argument.
continent
Optional continent filter over registration or headquarters country.
Clear enough to supply this argument.
entity_type
One or more GEM owner entity types, such as company, government, or person. Choices: get_parameter_options('energy_search_owners', 'entity_type').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
publicly_listed
Filter to publicly listed or non-listed owner entities.
Clear enough to supply this argument.
limit
Number of owner records per page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description98/100
First call for capacity rollups, energy mix breakdowns, transition tracking, ownership-share totals, and 'biggest / largest / top by capacity' questions across the Global Energy Monitor registry. For representative sites, pair this rollup with facilities_search (source=[gem]) and its public facility URLs; energy_search_assets is for deeper native detail. Group by country, region, continent, tracker, status, start_year_decade, fuel, or tier. Returns count + sum/avg/min/max capacity_mw + a status breakdown per bucket. CRITICAL: capacity_mw is only meaningful for power generation trackers (coal_plants, oil_gas_plants, nuclear, geothermal, bioenergy, hydropower, solar, wind); for coal_mines (Mtpa), coal_terminals (Mt), lng_terminals (Mtpa or Bcm/y), and oil_gas_extraction (no capacity), capacity_mw will be 0 — constrain with the tracker filter when summing capacity. Use for status-filtered native units and capacity by country/owner. Asset counts are not station counts; nameplate MW is not generation or uptime. Keep source vintage explicit.
The description explains the capability, when to use it, and what to expect.
Inputs93/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
group_by
Aggregation dimension. Use 'country' or 'region' for geographic rollups; 'tracker' for energy mix; 'status' for transition (operating vs proposed vs retired); 'start_year_decade' for vintage; 'fuel' for normalized fuel breakdown. Choices: get_parameter_options('energy_summarize_assets', 'group_by').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
tracker
Source tracker identifying the asset class; use trackers returned by energy_search_assets.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
country
One or more plain-English country names or ISO-3 codes; matches the asset's primary or secondary country. For a single country pass a one-element list. Choices: get_parameter_options('energy_summarize_assets', 'country').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
region
One plain-English region; expanded to its ISO-3 country list the same way as search_events.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
continent
One plain-English continent; expanded to its ISO-3 country list the same way as search_events.
One or more fuel values (native fuel string on oil_gas_plants; normalized on cross-tracker view).
Clear enough to supply this argument.
capacity_mw_min
Minimum capacity_mw before grouping.
Clear enough to supply this argument.
capacity_mw_max
Maximum capacity_mw before grouping.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
start_year_min
Earliest start_year before grouping.
Clear enough to supply this argument.
start_year_max
Latest start_year before grouping.
Clear enough to supply this argument.
owner_search
Owner substring filter before grouping.
Clear enough to supply this argument.
owner_entity_id
Owner identifier returned as entity_id by energy_search_owners; filters the portfolio before aggregation. Choices: get_parameter_options('energy_summarize_assets', 'owner_entity_id').
Clear enough to supply this argument.
asset_class
'fixed', 'mobile', or 'all'.
Clear enough to supply this argument.
summary_limit
Number of aggregate buckets to return, rather than individual Events or Stories.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description90/100
China overseas development-finance projects (AidData GCDF) — amounts, sector, status, financiers. Pair any recipient country with the live event stream (search_events) to see what's happening around China's footprint now. Returns data project records with recipient geography, financial amounts, sector/status and financier evidence, plus pagination and applied_filters. Project amounts retain their units and source meaning.
The description explains the capability, when to use it, and what to expect.
Inputs82/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
search
Project title search.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
country
Recipient country (ISO3 or name). Choices: get_parameter_options('china_projects_search', 'country').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
sector
Sector filter — exact case-insensitive match on an AidData sector (e.g. 'ENERGY', 'TRANSPORT AND STORAGE', 'GOVERNMENT AND CIVIL SOCIETY'). Enumerate the valid sectors via china_projects_summary(group_by='sector'). Choices: get_parameter_options('china_projects_search', 'sector').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
year_min
Minimum commitment year.
Clear enough to supply this argument.
completion_year_min
Minimum completion year (filters on completion_year).
Clear enough to supply this argument.
completion_year_max
Maximum completion year (filters on completion_year).
Clear enough to supply this argument.
sort
amount_desc (default) | recent.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
limit
Maximum number of projects.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description88/100
Rollup of China overseas development finance by sector or country — counts + total committed USD. Use before china_projects_search for shape-of-the-footprint questions.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
country
Recipient country filter. Choices: get_parameter_options('china_projects_summary', 'country').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
sector
Sector filter (exact AidData sector; see the sector bucket labels this tool returns). Choices: get_parameter_options('china_projects_summary', 'sector').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
group_by
Bucket dimension: sector | country | status | year | flow_class | intent. Each bucket enumerates that dimension's valid values — use this to discover sector/status/flow_class/intent vocab for china_projects_search.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description87/100
Precomputed ownership-chain exposure across three lenses (sanctions / china / state_owned) for energy assets (risk-per-MW rollups) or entities, with the contributing lists and the ownership paths that produced each flag. Use for 'which assets/entities in country X are exposed to sanctions/China/state ownership'.
The description explains the capability, when to use it, and what to expect.
Inputs90/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
lens
Exposure lens: sanctions | china | state_owned.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
subject
assets (energy, risk-per-MW) | entities. Auto-switches to entities when an entity handle (entity_id / entity_search) is given without an asset selector.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
country
Country ISO3/name filter(s). Choices: get_parameter_options('exposure_search', 'country').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
region
Region filter expanded by the REST API to its member countries.
Clear enough to supply this argument.
continent
Continent filter expanded by the REST API to its member countries.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
tracker
Source tracker identifying the asset class; use trackers returned by energy_search_assets.
Clear enough to supply this argument.
list
Restrict to a contributing list source_key (e.g. csl_ofac_sdn, eu_fsf, dod_1260h). Resolve a valid key via lists_catalog first.
Clear enough to supply this argument.
entity
Filter to one resolved terminal spine entity id. Choices: get_parameter_options('exposure_search', 'entity').
Clear enough to supply this argument.
entity_search
Fuzzy entity name resolved server-side before exposure filtering.
Clear enough to supply this argument.
gem_id
GEM asset identifier returned by energy_search_assets; reuse the selected asset gem_id. Choices: get_parameter_options('exposure_search', 'gem_id').
Clear enough to supply this argument.
min_stake_pct
Minimum effective ownership-chain stake. Unknown effective stakes never pass a numeric threshold.
Clear enough to supply this argument.
direct_only
Only direct (non-via-parent) exposure.
Clear enough to supply this argument.
group_by
assets grouping: none | country | tracker.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
sort
Result ordering by capacity or effective stake.
Clear enough to supply this argument.
limit
Maximum number of rows.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
offset
Number of records to skip before this page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
source
Deprecated alias for list.
Clear enough to supply this argument.
entity_id
Deprecated alias for entity. Choices: get_parameter_options('exposure_search', 'entity_id').
Clear enough to supply this argument.
counterparty
Deprecated alias for entity_search. Choices: get_parameter_options('exposure_search', 'counterparty').
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description90/100
Read published restricted-party list entries for a selected source, name or reference: organizations, people, vessels and aircraft, with source-reported programmes, aliases and country evidence. active_on selects historical membership; preserve publisher dates and attribution. Use for source-record lookup; a name match is not an identity determination, and no match is not compliance clearance.
The description explains the capability, when to use it, and what to expect.
Inputs91/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
source
Restrict to one source_key (eu_fsf, un_consolidated, uk_uksl, dod_1260h, ...). Enumerate valid source_keys via lists_catalog.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
search
Substring of the list-entry name or caption; useful after lists_catalog identifies the publisher/source.
Clear enough to supply this argument.
country
Country filter — accepts a country name or ISO-2/ISO-3 code (e.g. CHN, China, CN). Filtered against the entry's country. Choices: get_parameter_options('list_entries_search', 'country').
Clear enough to supply this argument.
region
One plain-English region (Middle East, Europe, Eastern Europe, South Asia, Western Africa, …). Expanded to its ISO-3 country list and applied the same way as `country`.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
continent
One plain-English continent (Asia, Europe, Africa, North America, South America, Oceania). Expanded to its ISO-3 country list and applied the same way as `country`.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
program
Publisher sanctions-program name to match; program vocabulary varies by source. Choices: get_parameter_options('list_entries_search', 'program').
Clear enough to supply this argument.
entity_id
Filter to entries resolved to this spine entity_id (resolve a name via unified_entity_search). Choices: get_parameter_options('list_entries_search', 'entity_id').
Clear enough to supply this argument.
active_on
Observation-date view of list membership in YYYY-MM-DD. Omission returns currently active entries; unavailable historical coverage remains inconclusive.
Clear enough to supply this argument.
limit
Maximum number of entries.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description94/100
Catalog of the restricted-party list sources we ingest (issuer, jurisdiction, cadence, current entry counts, category and publisher provenance). Includes original-publisher crawler sources. Select rows with ingested=true before drilling with list_entries_search.
The description explains the capability, when to use it, and what to expect.
Inputs65/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
source
Filter to one source_key. This tool IS the source_key catalog — call with no filters and use rows with ingested=true to enumerate currently accepted source_keys (the key to pass to exposure_search.source / list_entries_search.source).
Clear enough to supply this argument.
category
What KIND of list: sanctions | export_control | debarment | wanted | maritime | domestic_terror | screening_list. Only sanctions and export_control count toward the sanctions exposure lens; a debarment or wanted-person listing is catalogued and screenable but is NOT a sanction. Case-insensitive.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
jurisdiction
Issuer jurisdiction from the open source catalog; for example US, EU, UN or UK. Select the returned jurisdiction from lists_catalog. Choices: get_parameter_options('lists_catalog', 'jurisdiction').
Resolve the mismatch between this description and its schema constraints.
cadence
Publisher/source refresh schedule from the observed catalog. Returned suggestions are not an allowlist. Choices: get_parameter_options('lists_catalog', 'cadence').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
{
"if": {
"required": [
"_mcp_projection"
]
},
"else": {
"type": "object",
"required": [
"success",
"data",
"applied_filters"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"source_key",
"list_name",
"issuer",
"jurisdiction",
"authority",
"source_url",
"cadence",
"loader",
"includes_individuals",
"last_loaded",
"entry_count",
"category",
"publisher",
"publisher_country",
"official",
"licence",
"last_crawled",
"coverage_start",
"individual_count",
"superseded_by",
"retired_at",
"ingested"
],
"properties": {
"issuer": {
"type": "string"
},
"loader": {
"type": "string"
},
"cadence": {
"type": "string",
"description": "OUR refresh cadence (`daily` | `episodic`), not the publisher's."
},
"licence": {
"type": [
"string",
"null"
],
"description": "The publisher's licence / terms URL; null when not recorded."
},
"category": {
"type": [
"string",
"null"
],
"description": "sanctions | export_control | debarment | wanted | maritime | domestic_terror — from `ref.list_catalog.category` for crawler-lane sources, from the static legacy map for hand-loaded ones; null when neither knows."
},
"ingested": {
"type": [
"boolean",
"null"
],
"description": "Whether `list=<source_key>` is accepted RIGHT NOW on `/api/v2/lists/entries`, `/api/v2/lists/changes` and `/api/v2/exposure` — MEASURED from the catalogue (`ingested = 1` and a non-zero current entry count for a crawler-lane source; the registry for a hand-loaded one). The accepted set grows as sources are ingested, so this row, not the published enum, is the live answer. `null` only when the column has not been measured on this cluster."
},
"official": {
"type": [
"boolean",
"null"
],
"description": "Whether the publisher is the issuing authority; null when the catalogue has not recorded it."
},
"authority": {
"type": "string"
},
"list_name": {
"type": "string"
},
"publisher": {
"type": [
"string",
"null"
],
"description": "The publishing body as the catalogue records it; null when not recorded."
},
"retired_at": {
"type": [
"string",
"null"
],
"description": "The date this legacy source's rows were retired in favour of `superseded_by` — its entries became inactive and `/api/v2/lists/changes` records them as `removed` on that day. Null while the source is live, and null on a cluster where the retirement ledger column has not been created."
},
"source_key": {
"type": "string"
},
"source_url": {
"type": "string"
},
"entry_count": {
"type": "number"
},
"last_loaded": {
"type": [
"string",
"null"
]
},
"jurisdiction": {
"type": "string"
},
"last_crawled": {
"type": [
"string",
"null"
],
"description": "When the crawler lane last fetched the source; null for hand-loaded sources."
},
"superseded_by": {
"type": [
"string",
"null"
],
"description": "For a legacy (hand-loaded) source: the OSINT crawler-lane `source_key` that replaces it, from the catalogue successor map. `list=<this key>` resolves to it once the successor is ingested (see `applied_filters.deprecations[]`). Null for a source nothing supersedes."
},
"coverage_start": {
"type": [
"string",
"null"
],
"description": "Earliest observation date we hold for this source — the floor for `active_on` / `as_of`; null when the source has no rows."
},
"individual_count": {
"type": [
"number",
"null"
],
"description": "Current natural-person rows; null when the column has not been measured on this cluster."
},
"publisher_country": {
"type": [
"string",
"null"
],
"description": "ISO-3 of the publisher; null when not recorded."
},
"includes_individuals": {
"type": "boolean",
"description": "MEASURED: the source has projected at least one natural-person row. A person screen is scoped to sources where this is true."
}
}
}
},
"success": {
"type": "boolean"
},
"applied_filters": {}
}
},
"then": {
"type": "object",
"required": [
"_mcp_projection"
],
"properties": {
"data": {
"type": "array",
"description": "Compact records retain IDs, returned links, selected images, evidence and metrics where available; unknown values remain unknown."
},
"success": {
"type": "boolean"
},
"_mcp_projection": {
"type": "object",
"required": [
"mode"
],
"properties": {
"mode": {
"const": "compact"
},
"truncated": {
"type": "boolean"
}
},
"description": "Explicitly discloses omitted fields or shortened evidence."
},
"applied_filters": {}
}
},
"type": "object",
"description": "Full preserves the bounded API response. Compact preserves evidence, coverage, filters and pagination with explicit projection disclosure; neither fetches other pages."
}
Original tool metadata
{
"name": "lists_catalog",
"title": "List public list sources",
"description": "Catalog of the restricted-party list sources we ingest (issuer, jurisdiction, cadence, current entry counts, category and publisher provenance). Includes original-publisher crawler sources. Select rows with ingested=true before drilling with list_entries_search.",
"inputSchema": {
"type": "object",
"properties": {
"source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Filter to one source_key. This tool IS the source_key catalog — call with no filters and use rows with ingested=true to enumerate currently accepted source_keys (the key to pass to exposure_search.source / list_entries_search.source).",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "list_source_key",
"parameter": "source"
}
},
"cadence": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Publisher/source refresh schedule from the observed catalog. Returned suggestions are not an allowlist. Choices: get_parameter_options('lists_catalog', 'cadence').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "observed",
"enum_id": "list_cadence",
"parameter": "cadence"
}
},
"category": {
"anyOf": [
{
"enum": [
"sanctions",
"domestic_terror",
"debarment",
"export_control",
"screening_list",
"military_affiliation",
"wanted",
"maritime"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "What KIND of list: sanctions | export_control | debarment | wanted | maritime | domestic_terror | screening_list. Only sanctions and export_control count toward the sanctions exposure lens; a debarment or wanted-person listing is catalogued and screenable but is NOT a sanction. Case-insensitive.",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "closed",
"enum_id": "list_category",
"parameter": "category"
}
},
"jurisdiction": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Issuer jurisdiction from the open source catalog; for example US, EU, UN or UK. Select the returned jurisdiction from lists_catalog. Choices: get_parameter_options('lists_catalog', 'jurisdiction').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "open",
"parameter": "jurisdiction"
}
},
"response_mode": {
"enum": [
"compact",
"full"
],
"type": "string",
"default": "compact",
"description": "Compact chat projection or unchanged bounded full API response; neither fetches another page."
}
},
"additionalProperties": false
},
"outputSchema": {
"if": {
"required": [
"_mcp_projection"
]
},
"else": {
"type": "object",
"required": [
"success",
"data",
"applied_filters"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"source_key",
"list_name",
"issuer",
"jurisdiction",
"authority",
"source_url",
"cadence",
"loader",
"includes_individuals",
"last_loaded",
"entry_count",
"category",
"publisher",
"publisher_country",
"official",
"licence",
"last_crawled",
"coverage_start",
"individual_count",
"superseded_by",
"retired_at",
"ingested"
],
"properties": {
"issuer": {
"type": "string"
},
"loader": {
"type": "string"
},
"cadence": {
"type": "string",
"description": "OUR refresh cadence (`daily` | `episodic`), not the publisher's."
},
"licence": {
"type": [
"string",
"null"
],
"description": "The publisher's licence / terms URL; null when not recorded."
},
"category": {
"type": [
"string",
"null"
],
"description": "sanctions | export_control | debarment | wanted | maritime | domestic_terror — from `ref.list_catalog.category` for crawler-lane sources, from the static legacy map for hand-loaded ones; null when neither knows."
},
"ingested": {
"type": [
"boolean",
"null"
],
"description": "Whether `list=<source_key>` is accepted RIGHT NOW on `/api/v2/lists/entries`, `/api/v2/lists/changes` and `/api/v2/exposure` — MEASURED from the catalogue (`ingested = 1` and a non-zero current entry count for a crawler-lane source; the registry for a hand-loaded one). The accepted set grows as sources are ingested, so this row, not the published enum, is the live answer. `null` only when the column has not been measured on this cluster."
},
"official": {
"type": [
"boolean",
"null"
],
"description": "Whether the publisher is the issuing authority; null when the catalogue has not recorded it."
},
"authority": {
"type": "string"
},
"list_name": {
"type": "string"
},
"publisher": {
"type": [
"string",
"null"
],
"description": "The publishing body as the catalogue records it; null when not recorded."
},
"retired_at": {
"type": [
"string",
"null"
],
"description": "The date this legacy source's rows were retired in favour of `superseded_by` — its entries became inactive and `/api/v2/lists/changes` records them as `removed` on that day. Null while the source is live, and null on a cluster where the retirement ledger column has not been created."
},
"source_key": {
"type": "string"
},
"source_url": {
"type": "string"
},
"entry_count": {
"type": "number"
},
"last_loaded": {
"type": [
"string",
"null"
]
},
"jurisdiction": {
"type": "string"
},
"last_crawled": {
"type": [
"string",
"null"
],
"description": "When the crawler lane last fetched the source; null for hand-loaded sources."
},
"superseded_by": {
"type": [
"string",
"null"
],
"description": "For a legacy (hand-loaded) source: the OSINT crawler-lane `source_key` that replaces it, from the catalogue successor map. `list=<this key>` resolves to it once the successor is ingested (see `applied_filters.deprecations[]`). Null for a source nothing supersedes."
},
"coverage_start": {
"type": [
"string",
"null"
],
"description": "Earliest observation date we hold for this source — the floor for `active_on` / `as_of`; null when the source has no rows."
},
"individual_count": {
"type": [
"number",
"null"
],
"description": "Current natural-person rows; null when the column has not been measured on this cluster."
},
"publisher_country": {
"type": [
"string",
"null"
],
"description": "ISO-3 of the publisher; null when not recorded."
},
"includes_individuals": {
"type": "boolean",
"description": "MEASURED: the source has projected at least one natural-person row. A person screen is scoped to sources where this is true."
}
}
}
},
"success": {
"type": "boolean"
},
"applied_filters": {}
}
},
"then": {
"type": "object",
"required": [
"_mcp_projection"
],
"properties": {
"data": {
"type": "array",
"description": "Compact records retain IDs, returned links, selected images, evidence and metrics where available; unknown values remain unknown."
},
"success": {
"type": "boolean"
},
"_mcp_projection": {
"type": "object",
"required": [
"mode"
],
"properties": {
"mode": {
"const": "compact"
},
"truncated": {
"type": "boolean"
}
},
"description": "Explicitly discloses omitted fields or shortened evidence."
},
"applied_filters": {}
}
},
"type": "object",
"description": "Full preserves the bounded API response. Compact preserves evidence, coverage, filters and pagination with explicit projection disclosure; neither fetches other pages."
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description94/100
Published restricted-party list changes: additions, removals and amendments per snapshot day, with the entry name and source list. Use for source-attributed list-change reporting or a watchlist; use list_entries_search for membership evidence. An empty page alone does not establish no changes: inspect coverage and pagination; unavailable or incomplete history is unknown. A 400 on source means we do not carry that list. Publisher assertions are not an identity determination or compliance clearance.
The description explains the capability, when to use it, and what to expect.
Inputs89/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
source
Restrict to one list. Resolve a valid key via lists_catalog first — an unloaded key returns 400 LIST_SOURCE_NOT_AVAILABLE, which means we do NOT carry that list, NOT that nothing changed on it.
Clear enough to supply this argument.
change_type
Restrict to one kind of movement. Omit for all three.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
date
A single snapshot day (YYYY-MM-DD) instead of a range.
Clear enough to supply this argument.
date_start
Inclusive window start (YYYY-MM-DD).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
date_end
Inclusive window end (YYYY-MM-DD).
Clear enough to supply this argument.
days
Length of the trailing list-change window in days when explicit dates are omitted.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
limit
Maximum number of change rows.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description95/100
Compare a supplied name or organizational identifier against published restricted-party lists. Returns candidate identity evidence, publisher list/programme references, dates and optional reported ownership-chain exposure. Supports organizations, public-source person records, vessels and aircraft. Similarity or a shared name is not proof of identity; inspect corroborating source evidence. A no-match result is not clearance, and list categories differ. Use for researching a counterparty's published list evidence; no legal/compliance determination or enforcement action is made. Do not supply private personal government identifiers.
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
q
Counterparty name to screen against restricted-party lists.
Clear enough to supply this argument.
id
Strong id (LEI / registration number) for an exact, deterministic match. Choices: get_parameter_options('screening_match', 'id').
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
as_of
Historical observation date in YYYY-MM-DD. Omission screens currently active memberships; historical gaps remain inconclusive rather than a clean result.
Clear enough to supply this argument.
min_match_confidence
Threshold for calibrated identity confidence. Retrieval similarity is returned separately and is not a probability.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
include_exposure
Attach ownership-chain exposure context to accepted matches.
Clear enough to supply this argument.
threshold
Deprecated alias for min_match_confidence.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
limit
Maximum number of matches.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
nationality
PERSON EVIDENCE, not a filter. Nationality / citizenship of the subject as ISO-3 codes (e.g. ['IRN','IRQ']). Compared against each candidate's country_iso3 and reported per candidate as evidence.nationality (match | mismatch | unknown). It never narrows retrieval and never rejects on its own, because list country fields are inconsistently populated. An unresolvable code returns 400 INVALID_COUNTRY.
Clear enough to supply this argument.
birth_year
PERSON EVIDENCE, not a filter. Year of birth of the subject, compared with a ±1 tolerance because lists publish approximate and circa dates. A candidate whose recorded year contradicts it beyond that tolerance moves to rejected_candidates with decision_evidence: birth_year_mismatch; agreement is reported as evidence.birth_year: match; a candidate with no recorded year is unknown and stays a candidate. There is deliberately no date-of-birth parameter — the served person field is a YEAR.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description91/100
LLM-classified SEC 8-K material events (acquisitions, executive changes, results, guidance, restructuring, ...) with headline, named counterparties, and resolved spine entity_ids. Filter by filer CIK, a resolved entity, event_type, headline text, or date window (≤30 days). Returns data material-event records with accession_no, cik, event_type, headline, evidence text and resolved_entities, plus pagination and applied_filters. Extracted classifications are not independently verified causal claims.
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cik
SEC Central Index Keys from filings_resolve or filings_search. Comma-separate multiple CIKs to combine filers; leading zero padding is accepted. Choices: get_parameter_options('filings_events', 'cik').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
entity_id
Restrict to 8-K events referencing this resolved spine entity_id (as filer OR named counterparty). Resolve a name→entity_id via unified_entity_search / filings_resolve. Alias: entity. Choices: get_parameter_options('filings_events', 'entity_id').
Clear enough to supply this argument.
event_type
Material business-event classification extracted from the filing.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
search
Literal substring of the material-event headline.
Clear enough to supply this argument.
date_start
Window start YYYY-MM-DD (≤30-day window).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
date_end
Window end YYYY-MM-DD.
Clear enough to supply this argument.
days
Trailing N-day window.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
limit
Maximum number of events.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description88/100
XBRL structured financial facts for a filer (us-gaap / dei concept time series) — for exposure sizing (segment revenue, assets, net income). Returns data concept/taxonomy facts with value, unit, fiscal period, filed date and accession_no, plus cik, pagination and applied_filters. Keep facts with unlike periods or units separate.
The description explains the capability, when to use it, and what to expect.
Inputs92/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cik
SEC Central Index Key returned by filings_resolve or filings_search. Reuse the filer CIK; leading zero padding is accepted. Choices: get_parameter_options('filings_get_facts', 'cik').
Clear enough to supply this argument.
concept
XBRL concept tag (e.g. Revenues, NetIncomeLoss, Assets). Large open XBRL vocabulary — call with no concept to see which tags this filer reports.
Clear enough to supply this argument.
taxonomy
Taxonomy filter: us-gaap | dei.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
limit
Maximum number of facts.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description76/100
One filer's profile: identity, ticker, spine entity_id, recent filings, and XBRL financial highlights. The hub for a single company.
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cik
SEC Central Index Key returned by filings_resolve or filings_search. Reuse the filer CIK; leading zero padding is accepted. Choices: get_parameter_options('filings_get_filer', 'cik').
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description80/100
LLM-extracted subsidiary / supplier / customer / jurisdiction edges disclosed in a filer's Exhibit 21 + Item 1A, resolved to spine entity_ids with verbatim evidence — the supply-chain graph. Traverse from a disruption event to exposed public companies.
The description explains the capability, when to use it, and what to expect.
Inputs91/100
Explain what happens when this optional value is omitted.
cik
SEC Central Index Key returned by filings_resolve or filings_search. Reuse the filer CIK; leading zero padding is accepted. Choices: get_parameter_options('filings_get_relations', 'cik').
Clear enough to supply this argument.
rel_type
Kind of extracted counterparty relationship to select; read its dated source evidence before treating it as an established link.
Explain what happens when this optional value is omitted.
country
Object (counterparty) country filter — accepts a country name or ISO-2/ISO-3 code — matches object_country_iso3 on jurisdiction-exposure / counterparty edges. Choices: get_parameter_options('filings_get_relations', 'country').
Clear enough to supply this argument.
region
One plain-English region (Middle East, Europe, Eastern Europe, South Asia, Western Africa, …). Expanded to its ISO-3 country list and applied the same way as `country` (object/counterparty country).
Clear enough to supply this argument.
continent
One plain-English continent (Asia, Europe, Africa, North America, South America, Oceania). Expanded to its ISO-3 country list and applied the same way as `country`.
Clear enough to supply this argument.
limit
Maximum number of relations.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description98/100
Resolve a ticker / CIK / company name to its SEC CIK and spine entity_id. Start here to bridge a company in the news to its filings and the cross-source entity graph. Returns query, ranked candidates, nullable resolved and spine_fallback_used. Inspect candidate match evidence and has_sec_filings; a spine-only candidate does not establish SEC coverage.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
q
Company-name query. Canonical spelling shared with the REST endpoint.
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
cik
SEC Central Index Key returned by filings_resolve or filings_search. Reuse the filer CIK; leading zero padding is accepted. Choices: get_parameter_options('filings_resolve', 'cik').
Clear enough to supply this argument.
min_score
Minimum fuzzy-name candidate score.
Explain the meaning of this value, not just its name.
limit
Maximum resolver candidates.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
name
Deprecated alias for q.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description83/100
Search the SEC EDGAR filing index by company (CIK), form type (10-K/8-K/4/13F/...), name, and date window (≤30 days). Use for 'what did <company> file' / 'recent 8-Ks' questions.
The description explains the capability, when to use it, and what to expect.
Inputs81/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cik
SEC Central Index Keys from filings_resolve or filings_search. Comma-separate multiple CIKs to combine filers; leading zero padding is accepted. Choices: get_parameter_options('filings_search', 'cik').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
form_type
One or more SEC form types, e.g. ['10-K','8-K','424B2']. Open vocabulary; get_parameter_options provides observed suggestions, and other form strings remain accepted. Choices: get_parameter_options('filings_search', 'form_type').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
search
Company-name search.
Explain the meaning of this value, not just its name.
country
Filer business country — accepts a country name or ISO-2/ISO-3 code (e.g. US, CN, JP, USA, China). Filtered against the filer's business country. Choices: get_parameter_options('filings_search', 'country').
Clear enough to supply this argument.
region
One plain-English region (Middle East, Europe, Eastern Europe, South Asia, Western Africa, …). Expanded to its ISO-3 country list and applied the same way as `country` (filer business country).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
continent
One plain-English continent (Asia, Europe, Africa, North America, South America, Oceania). Expanded to its ISO-3 country list and applied the same way as `country`.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
date_start
Window start YYYY-MM-DD (≤30-day window).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
date_end
Window end YYYY-MM-DD.
Clear enough to supply this argument.
days
Trailing N-day window.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
sort
recent | filer.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
limit
Maximum number of filings.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description95/100
Rollup of filings by form type, date, or filer — counts + distinct filers. Call before filings_search for shape-of-activity questions. Returns group_by, data aggregate buckets and pagination with total_buckets/truncated. Counts describe filings and distinct filers rather than financial totals.
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
group_by
form_type | date | filer.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
form_type
Restrict the rollup to one or more SEC form types. Open vocabulary; observed choices are available through get_parameter_options. Choices: get_parameter_options('filings_summary', 'form_type').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
country
Filer business country — accepts a country name or ISO-2/ISO-3 code (e.g. US, CN, USA, China). Scopes the rollup to that filer business country. Choices: get_parameter_options('filings_summary', 'country').
Clear enough to supply this argument.
region
One plain-English region (Middle East, Europe, Eastern Europe, South Asia, Western Africa, …). Expanded to its ISO-3 country list and applied the same way as `country` (filer business country).
Clear enough to supply this argument.
continent
One plain-English continent (Asia, Europe, Africa, North America, South America, Oceania). Expanded to its ISO-3 country list and applied the same way as `country`.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
date_start
Window start YYYY-MM-DD.
Clear enough to supply this argument.
date_end
Window end YYYY-MM-DD.
Clear enough to supply this argument.
days
Trailing N-day window.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
limit
Maximum number of buckets.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description92/100
Aggregate vessel activity over a chokepoint / bbox / proximity area, bucketed by hour or day (≤30-day window) — distinct vessels, positions, moving positions, and avg/max speed per bucket. The 'is this area's traffic anomalous vs the baseline' view; generalizes maritime_transits to arbitrary geography. Reads raw positions; admin-only. Returns bucket, data time buckets with vessels, positions, moving_positions and avg_sog/max_sog in knots, plus pagination and applied_filters. Position counts are observations, not vessel counts.
The description explains the capability, when to use it, and what to expect.
Inputs91/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
chokepoint
Named maritime passage to select. Omission includes all passages covered by this operation.
Clear enough to supply this argument.
bbox
Bounding box 'minLon,minLat,maxLon,maxLat'. NOTE: lon-first axis order (opposite of the lat-first bbox on events/stories/energy).
Clear enough to supply this argument.
near
Return activity within radius_km of a point, formatted 'lat,lon'. Default radius 50 km.
Clear enough to supply this argument.
near_gem_id
GEM asset identifier from energy_search_assets, used as the center for nearby vessel or port observations. Choices: get_parameter_options('maritime_activity', 'near_gem_id').
Clear enough to supply this argument.
radius_km
Radius in km for near / near_gem_id (defaults: 50 for near, 25 for near_gem_id).
Clear enough to supply this argument.
bucket
Time bucket: 'hour' or 'day'. Auto-picks hour for ≤2-day spans, else day.
Clear enough to supply this argument.
date_start
Window start YYYY-MM-DD (≤30-day window).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
date_end
Window end YYYY-MM-DD.
Explain what happens when this optional value is omitted.
days
Trailing N-day window.
Explain what happens when this optional value is omitted.
limit
Maximum number of buckets.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description92/100
The maritime risk layer — per-chokepoint AIS coverage confidence fused with GDELT Cloud Conflict Events (7d) in the bordering countries, surfacing 'blind spots' (conflict signal but no vessel coverage) and a risk_level per chokepoint, with recent conflict headlines + energy exposure. The headline maritime-risk product for non-maritime-native analysts. Start here for 'where's maritime risk rising / where are we blind' questions.
The description explains the capability, when to use it, and what to expect.
Inputs95/100
Input documentation gives an agent enough context to populate the arguments.
chokepoint
Named maritime passage to select. Omission includes all passages covered by this operation.
Clear enough to supply this argument.
blind_spots_only
true → only chokepoints that are 'blind spots' — conflict signal in the bordering countries but no vessel coverage.
Clear enough to supply this argument.
min_conflict
Minimum 7-day conflict-event count in the bordering countries to include a chokepoint.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description93/100
Spatial density grid (heatmap) of position + vessel counts per lat/lon cell over a ≤7-day window. Requires an area — bbox, near, or near_gem_id. Shows where traffic concentrates inside an area. Reads raw positions; admin-only. Returns cell_deg and data cells with cell_lat/cell_lon, positions and vessels, plus pagination and applied_filters. Cells describe observed traffic concentration, not exhaustive coverage.
The description explains the capability, when to use it, and what to expect.
Inputs80/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
bbox
Bounding box 'minLon,minLat,maxLon,maxLat' (lon-first). AREA REQUIRED: pass bbox, near, or near_gem_id.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
near
Point 'lat,lon' for a radius area; combine with radius_km. Default radius 50 km. AREA REQUIRED.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
near_gem_id
GEM asset identifier from energy_search_assets, used as the center for nearby vessel or port observations. Choices: get_parameter_options('maritime_density', 'near_gem_id').
Clear enough to supply this argument.
radius_km
Radius in km for near / near_gem_id (defaults: 50 for near, 25 for near_gem_id).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cell_deg
Latitude/longitude grid-cell width in degrees; smaller cells produce a finer traffic heatmap.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
date_start
Window start YYYY-MM-DD (≤7-day window).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
date_end
Inclusive UTC end date of the vessel-position window. Omission uses the current UTC date.
Clear enough to supply this argument.
days
Trailing N-day window.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
limit
Maximum number of grid cells.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description94/100
Vessel dwell episodes inside a chokepoint (arrival → departure, hours) — a congestion / loitering signal. Pair with event intensity for disruption analysis. Returns data dated dwell episodes with vessel identity and elapsed hours, plus pagination/applied_filters; an episode alone does not establish a disruption cause.
The description explains the capability, when to use it, and what to expect.
Inputs86/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
chokepoint
Named maritime passage to select. Omission includes all passages covered by this operation.
Clear enough to supply this argument.
date_start
Window start YYYY-MM-DD.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
date_end
Window end YYYY-MM-DD.
Explain what happens when this optional value is omitted.
days
Trailing N-day window.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
limit
Maximum number of dwell episodes.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description97/100
One vessel by IMO: identity, last-known position, and GEM LNG-carrier linkage. Use to bridge a tanker/carrier in the news to the energy-asset graph. Returns vessel identity, its last-known position and any GEM linkage. Missing linkage is unknown coverage rather than proof the vessel has no owner or registry record.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
imo
International Maritime Organization vessel identifier returned by maritime_vessels or maritime_get_carrier. Choices: get_parameter_options('maritime_get_carrier', 'imo').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description91/100
Port-level disruption intelligence — fuses the ports reference with GDELT Cloud Events near each port (event volume, conflict signal, a 7d-vs-baseline anomaly ratio, recent headlines) plus nearby energy-asset exposure and AIS-coverage context. The supply-chain / commodity product: 'which ports are making news, with what, and do we have maritime visibility there.' Scope by country, terminal type, or proximity. Returns port records with nearby reported Events, anomaly comparisons, energy exposure and AIS coverage context. Retain the signal windows and coverage; proximity is not established site impact.
The description explains the capability, when to use it, and what to expect.
Inputs92/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
country
Country filter — accepts a country name or ISO-2/ISO-3 code (e.g. UKR, EGY, Ukraine, UA) to scope the ports in view. Choices: get_parameter_options('maritime_port_pulse', 'country').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
region
One plain-English region (Middle East, Europe, Eastern Europe, South Asia, Western Africa, …). Expanded to its ISO-3 country list and applied the same way as `country` to scope the ports in view.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
continent
One plain-English continent (Asia, Europe, Africa, North America, South America, Oceania). Expanded to its ISO-3 country list and applied the same way as `country`.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
search
Port name / UN/LOCODE (substring) to scope to specific ports (e.g. 'Odesa').
Clear enough to supply this argument.
unlocode
United Nations port location code returned by maritime_ports; selects that port. Choices: get_parameter_options('maritime_port_pulse', 'unlocode').
Clear enough to supply this argument.
lng_terminal
true → only ports with an LNG terminal.
Clear enough to supply this argument.
oil_terminal
true → only ports with an oil terminal.
Clear enough to supply this argument.
min_harbor_size
Minimum harbor size: very_small | small | medium | large.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
near_gem_id
GEM asset identifier from energy_search_assets, used as the center for nearby vessel or port observations. Choices: get_parameter_options('maritime_port_pulse', 'near_gem_id').
Clear enough to supply this argument.
near
Scope to ports within radius_km of a point, formatted 'lat,lon'. Default radius 200 km.
Clear enough to supply this argument.
bbox
Bounding box 'minLon,minLat,maxLon,maxLat' (lon-first) to scope the ports.
Clear enough to supply this argument.
radius_km
Radius in km for near / near_gem_id (default 200).
Clear enough to supply this argument.
days
GDELT Cloud Event window in days (default 14).
Clear enough to supply this argument.
event_radius_km
How close (km) an event must be to a port to count for it (default 50).
Clear enough to supply this argument.
limit
Maximum number of ports.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description86/100
The open-data ports reference (NGA World Port Index) — ~3,800 ports with coordinates, UN/LOCODE, harbor size/type/use, max vessel draft + channel depth, and LNG/oil/container terminal facilities. Filter by name, country, UN/LOCODE, minimum size, terminal type, bbox, or proximity to a point / GEM energy asset (near_gem_id — the ports↔energy join). Open-data reference, not derived AIS.
The description explains the capability, when to use it, and what to expect.
Inputs90/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
search
Port name / alternate name (substring) or exact UN/LOCODE (e.g. 'Rotterdam', 'NLRTM').
Clear enough to supply this argument.
country
Country filter — accepts a country name or ISO-2/ISO-3 code (e.g. NLD, CHN, USA, Netherlands, CN). Filtered against the port's country. Choices: get_parameter_options('maritime_ports', 'country').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
region
One plain-English region (Middle East, Europe, Eastern Europe, South Asia, Western Africa, …). Expanded to its ISO-3 country list and applied the same way as `country`.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
continent
One plain-English continent (Asia, Europe, Africa, North America, South America, Oceania). Expanded to its ISO-3 country list and applied the same way as `country`.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
unlocode
United Nations port location code returned by maritime_ports; selects that port. Choices: get_parameter_options('maritime_ports', 'unlocode').
Clear enough to supply this argument.
min_harbor_size
Minimum harbor size: very_small | small | medium | large.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
lng_terminal
true → only ports with an LNG terminal.
Clear enough to supply this argument.
oil_terminal
true → only ports with an oil terminal.
Clear enough to supply this argument.
near_gem_id
GEM asset identifier from energy_search_assets, used as the center for nearby vessel or port observations. Choices: get_parameter_options('maritime_ports', 'near_gem_id').
Clear enough to supply this argument.
near
Return ports within radius_km of a point, formatted 'lat,lon'. Default radius 100 km.
Clear enough to supply this argument.
bbox
Bounding box 'minLon,minLat,maxLon,maxLat' (lon-first, as on the other maritime endpoints).
Clear enough to supply this argument.
radius_km
Radius in km for near / near_gem_id (default 100).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
limit
Maximum number of ports.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description88/100
⚠️ Raw position points (time, position, speed, course, nav status) inside an area over a ≤7-day window. Requires an area — chokepoint, bbox, near, or near_gem_id. Returns an opaque keyset next_cursor; follow it to stitch a long period in pages. The historical/baseline surface — admin-only raw-position preview. Returns data position points with vessel/time identity, coordinates and movement fields, plus pagination.next_cursor. Continue with unchanged area and dates; these are observed fixes, not a complete voyage.
Resolve contradictions between the description, input schema, and annotations.
Inputs89/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
chokepoint
Named maritime passage to select. Omission includes all passages covered by this operation.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
bbox
Bounding box 'minLon,minLat,maxLon,maxLat' (lon-first). AREA REQUIRED: pass chokepoint, bbox, near, or near_gem_id.
Clear enough to supply this argument.
near
Point 'lat,lon' for a radius area; combine with radius_km. Default radius 50 km. AREA REQUIRED.
Clear enough to supply this argument.
near_gem_id
GEM asset identifier from energy_search_assets, used as the center for nearby vessel or port observations. Choices: get_parameter_options('maritime_tracks', 'near_gem_id').
Clear enough to supply this argument.
radius_km
Radius in km for near / near_gem_id (defaults: 50 for near, 25 for near_gem_id).
Clear enough to supply this argument.
date_start
Window start YYYY-MM-DD (≤7-day window).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
date_end
Window end YYYY-MM-DD.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
days
Trailing N-day window.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
limit
Number of vessel-position points on this page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description88/100
Hourly vessel-transit activity through a maritime chokepoint (Hormuz, Bab-el-Mandeb, Malacca, Suez, Panama, …) — distinct + moving vessel counts and average speed over a ≤30-day window. Start here for 'how has traffic through <chokepoint> changed' questions.
The description explains the capability, when to use it, and what to expect.
Inputs86/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
chokepoint
Named maritime passage to select. Omission includes all passages covered by this operation.
Clear enough to supply this argument.
date_start
Window start YYYY-MM-DD (≤30-day window).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
date_end
Window end YYYY-MM-DD.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
days
Trailing N-day window.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
limit
Maximum number of rows.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description93/100
⚠️ Raw position track for one vessel by IMO — the literal 'this ship over time', every position across a ≤30-day window, time-ordered. Returns an opaque keyset next_cursor; follow it to stitch a long period in pages. Admin-only raw-position preview.
The description explains the capability, when to use it, and what to expect.
Inputs86/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
imo
International Maritime Organization vessel identifier returned by maritime_vessels or maritime_get_carrier. Choices: get_parameter_options('maritime_vessel_track', 'imo').
Clear enough to supply this argument.
date_start
Window start YYYY-MM-DD (≤30-day window).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
date_end
Window end YYYY-MM-DD.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
days
Trailing N-day window.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
limit
Number of vessel-position points on this page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description90/100
Current vessels with last-known position (lat/lon) + identity (name, ship type, flag, IMO/MMSI, call sign). Search by name/IMO, filter by chokepoint, or run a geo/proximity query — including near_gem_id to find vessels near a GEM energy asset (the cross-source maritime↔energy join). Raw track history is never exposed — last-known only.
The description explains the capability, when to use it, and what to expect.
Inputs92/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Chokepoint containing the vessel last-known position. Select one schema value; this parameter does not accept a list.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
near_gem_id
GEM asset identifier from energy_search_assets, used as the center for nearby vessel or port observations. Choices: get_parameter_options('maritime_vessels', 'near_gem_id').
Clear enough to supply this argument.
near
Return vessels within radius_km of a point, formatted 'lat,lon'. Default radius 50 km.
Clear enough to supply this argument.
bbox
Bounding box 'minLon,minLat,maxLon,maxLat'. NOTE: lon-first axis order (opposite of the lat-first bbox on events/stories/energy).
Clear enough to supply this argument.
radius_km
Radius in km for near / near_gem_id (defaults: 50 for near, 25 for near_gem_id).
Clear enough to supply this argument.
limit
Maximum number of vessels.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description86/100
One series' metadata — title, units, frequency, source agency, geo, license tier. Call after macro_search_series to confirm the right series before pulling observations.
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
series_id
FRED series id (e.g. GDP, CPIAUCSL, DGS10, DCOILBRENTEU). Use macro_search_series first to find a valid id. Choices: get_parameter_options('macro_get_series', 'series_id').
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description93/100
Values over time for a series, optionally restricted to an available ALFRED vintage (as_of). Check returned observation dates and vintage; historical coverage varies by series and date. Use for then-known values only when the requested vintage is actually returned. An empty historical vintage is unknown coverage; never substitute current revisions or claim a backtest-ready result.
The description explains the capability, when to use it, and what to expect.
Inputs96/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
series_id
FRED series id. Use macro_search_series first to find a valid id (see https://docs.gdeltcloud.com/api-reference/macro-series-catalog). Choices: get_parameter_options('macro_observations', 'series_id').
Clear enough to supply this argument.
date_start
Inclusive observation-date lower bound in YYYY-MM-DD. Omission includes the series history from the REST floor of 1900-01-01.
Clear enough to supply this argument.
date_end
Inclusive observation-date upper bound in YYYY-MM-DD. Omission imposes no current-date cutoff and includes all loaded observations.
Clear enough to supply this argument.
as_of
ALFRED vintage date YYYY-MM-DD — values AS THEY WERE KNOWN on that date (no look-ahead). Use for point-in-time backtests / event-study ground truth.
Clear enough to supply this argument.
limit
Maximum number of observations.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description95/100
DISCOVER / enumerate the FRED economic-series catalog (GDP, CPI, policy rates, employment, Brent/WTI, ...). Call with NO filters to list the full curated catalog; or narrow by text / agency / frequency / geo. START HERE to resolve a human request to a valid series_id before calling macro_get_series or macro_observations.
The description explains the capability, when to use it, and what to expect.
Inputs84/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
search
Free-text search over series id / title (e.g. 'unemployment', 'brent', 'CPI').
Clear enough to supply this argument.
agency
Source agency from the complete current REST vocabulary; case-insensitive.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
frequency
FRED frequency word (Daily/Weekly/Monthly/Quarterly/Annual) or code (D/W/M/Q/A); case-insensitive.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
geo
Country ISO3 the series describes (e.g. USA, CHN). Choices: get_parameter_options('macro_search_series', 'geo').
Clear enough to supply this argument.
seasonal_adjustment
FRED seasonal adjustment basis from the current REST vocabulary; case-insensitive.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
limit
Maximum number of series.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description84/100
Read Epoch AI logic, packaging and memory component estimates for AI hardware supply research. Chip totals, designer totals and supply denominators remain separate source collections. Filter by participant entity/role, collection, country or name substring q; follow cursor pagination. Retain native units, periods and uncertainty; these observations are not interchangeable or additive capacity totals.
The description explains the capability, when to use it, and what to expect.
Inputs94/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
entity
Participant entity: spine id, news id, Wikipedia URL or resolved name. Unresolved names return 404. Choices: get_parameter_options('epoch_chip_components', 'entity').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
participant_role
Source-supported role of the selected entity in the record; distinguish owners, operators, financiers and users. A hardware ownership role does not establish ownership of a building. Choices: get_parameter_options('epoch_chip_components', 'participant_role').
Clear enough to supply this argument.
collection
Source collection identifier returned by these observations or the coverage catalog; narrows to that dataset collection. Choices: get_parameter_options('epoch_chip_components', 'collection').
Clear enough to supply this argument.
country
Exact ISO-3 country when the source reports one. Choices: get_parameter_options('epoch_chip_components', 'country').
Clear enough to supply this argument.
q
Substring of the observation name.
Clear enough to supply this argument.
limit
Number of records to return on this page; use the returned continuation to request the next page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description95/100
Read Epoch AI chip ownership estimates to compare reported compute holdings. Returns quarterly and cumulative estimates, participants, native units, median and uncertainty fields where available. Filter by participant entity/role, collection, country or name substring q; follow cursor pagination. Hardware ownership does not establish building ownership; do not add quarterly and cumulative figures together.
The description explains the capability, when to use it, and what to expect.
Inputs94/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
entity
Participant entity: spine id, news id, Wikipedia URL or resolved name. Unresolved names return 404. Choices: get_parameter_options('epoch_chip_owners', 'entity').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
participant_role
Source-supported role of the selected entity in the record; distinguish owners, operators, financiers and users. A hardware ownership role does not establish ownership of a building. Choices: get_parameter_options('epoch_chip_owners', 'participant_role').
Clear enough to supply this argument.
collection
Source collection identifier returned by these observations or the coverage catalog; narrows to that dataset collection. Choices: get_parameter_options('epoch_chip_owners', 'collection').
Clear enough to supply this argument.
country
Exact ISO-3 country when the source reports one. Choices: get_parameter_options('epoch_chip_owners', 'country').
Clear enough to supply this argument.
q
Substring of the observation name.
Clear enough to supply this argument.
limit
Number of records to return on this page; use the returned continuation to request the next page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description85/100
Epoch AI chip-sales rollup — cumulative installed compute by chip designer (H100-equivalent), unit counts, and power draw (MW) at the latest reported window per manufacturer. Sorted by installed compute desc. The 'how much compute has each designer shipped' view. Pagination only.
The description explains the capability, when to use it, and what to expect.
Inputs86/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
limit
Maximum number of chip-designer rows.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
offset
Number of records to skip before this page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
entity
Participant entity: spine ID, Wikipedia URL or resolved name. Choices: get_parameter_options('epoch_chip_sales', 'entity').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
participant_role
Source-supported role of the selected entity in the record; distinguish owners, operators, financiers and users. A hardware ownership role does not establish ownership of a building. Choices: get_parameter_options('epoch_chip_sales', 'participant_role').
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description89/100
Read Epoch AI lab compute-use estimates and supporting calculations to research who uses reported AI compute. Preserves native units, reference periods, participants and uncertainty. Filter by participant entity/role, collection, country or name substring q; follow cursor pagination. Compute use does not establish hardware or facility ownership; missing observations remain unknown.
The description explains the capability, when to use it, and what to expect.
Inputs94/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
entity
Participant entity: spine id, news id, Wikipedia URL or resolved name. Unresolved names return 404. Choices: get_parameter_options('epoch_chip_users', 'entity').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
participant_role
Source-supported role of the selected entity in the record; distinguish owners, operators, financiers and users. A hardware ownership role does not establish ownership of a building. Choices: get_parameter_options('epoch_chip_users', 'participant_role').
Clear enough to supply this argument.
collection
Source collection identifier returned by these observations or the coverage catalog; narrows to that dataset collection. Choices: get_parameter_options('epoch_chip_users', 'collection').
Clear enough to supply this argument.
country
Exact ISO-3 country when the source reports one. Choices: get_parameter_options('epoch_chip_users', 'country').
Clear enough to supply this argument.
q
Substring of the observation name.
Clear enough to supply this argument.
limit
Number of records to return on this page; use the returned continuation to request the next page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description83/100
Epoch AI company tracker — the tracked AI labs with latest valuation, annualized revenue, total equity funding, staff count, and company type (latest financials derived from the dated time-series; valuation = most recent CLOSED round). Sorted by valuation desc. Pagination only.
The description explains the capability, when to use it, and what to expect.
Inputs83/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
limit
Maximum number of companies.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
offset
Number of records to skip before this page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
entity
Participant entity: spine ID, Wikipedia URL or resolved name. Choices: get_parameter_options('epoch_companies', 'entity').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
participant_role
Source-supported role of the selected entity in the record; distinguish owners, operators, financiers and users. A hardware ownership role does not establish ownership of a building. Choices: get_parameter_options('epoch_companies', 'participant_role').
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description86/100
Epoch AI data-center registry — the largest AI compute clusters with power (MW), H100-equivalent compute, capital cost ($B), owner, chip types, and named users. Sorted by compute (H100e) desc; the response also includes a per-country rollup and dataset totals. Filter by country or owner.
The description explains the capability, when to use it, and what to expect.
Inputs84/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
country
Country filter — accepts a country name or ISO-2/ISO-3 code (e.g. United States, China, Malaysia, US, CHN). Case-insensitive; matched against the data center's country. Choices: get_parameter_options('epoch_data_centers', 'country').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
region
One plain-English region (Middle East, Europe, Eastern Europe, South Asia, Western Africa, …). Expanded to its ISO-3 country list and applied the same way as `country`.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
continent
One plain-English continent (Asia, Europe, Africa, North America, South America, Oceania). Expanded to its ISO-3 country list and applied the same way as `country`.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Explain the meaning of this value, not just its name.
owner_search
Substring match on the operating owner (free text, ~14 owners, e.g. Google, Meta, Microsoft, Oracle, CoreWeave, Amazon, xAI). Resolve a canonical owner via unified_entity_search. Sent to the API as owner (alias: org).
Clear enough to supply this argument.
limit
Maximum number of data centers.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
offset
Number of records to skip before this page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
entity
Participant entity: spine ID, Wikipedia URL or resolved name. Choices: get_parameter_options('epoch_data_centers', 'entity').
Clear enough to supply this argument.
participant_role
Source-supported role of the selected entity in the record; distinguish owners, operators, financiers and users. A hardware ownership role does not establish ownership of a building. Choices: get_parameter_options('epoch_data_centers', 'participant_role').
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description96/100
Read Epoch AI GPU cluster observations for research into compute infrastructure. Returns reported hardware, status, certainty, source evidence and participants; a cluster is distinct from a physical building. Filter by participant entity/role, collection, country or name substring q. Follow cursor pagination and retain native units, dated observations, uncertainty and coverage; no hardware inventory is inferred from missing records.
The description explains the capability, when to use it, and what to expect.
Inputs91/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
entity
Participant entity: spine id, news id, Wikipedia URL or resolved name. Unresolved names return 404. Choices: get_parameter_options('epoch_gpu_clusters', 'entity').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
participant_role
Source-supported role of the selected entity in the record; distinguish owners, operators, financiers and users. A hardware ownership role does not establish ownership of a building. Choices: get_parameter_options('epoch_gpu_clusters', 'participant_role').
Clear enough to supply this argument.
collection
Source collection identifier returned by these observations or the coverage catalog; narrows to that dataset collection. Choices: get_parameter_options('epoch_gpu_clusters', 'collection').
Clear enough to supply this argument.
country
Exact ISO-3 country when the source reports one. Choices: get_parameter_options('epoch_gpu_clusters', 'country').
Clear enough to supply this argument.
q
Substring of the observation name.
Clear enough to supply this argument.
limit
Number of records to return on this page; use the returned continuation to request the next page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description87/100
Epoch AI ML-hardware catalog — accelerators (GPU / TPU / NPU / GPGPU / ASIC) with manufacturer, release date, TDP (W), memory + bandwidth, process size, transistor count, and FP16/FP8 throughput. Sorted by release date desc. Filter by manufacturer or type. Returns data accelerator records with native specification units, release-date metadata and source-supported participant identities, plus pagination/applied_filters. Unknown specifications remain null.
The description explains the capability, when to use it, and what to expect.
Inputs80/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
manufacturer
Substring match on the manufacturer (free text, ~20 makers, e.g. NVIDIA, AMD, Google, Huawei, Cambricon, Intel). Alias: org. Choices: get_parameter_options('epoch_hardware', 'manufacturer').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
type
Accelerator architecture class used to narrow the hardware catalog.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
date_start
Release-date window start YYYY-MM-DD (filters on release_date).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
date_end
Release-date window end YYYY-MM-DD (filters on release_date).
Clear enough to supply this argument.
limit
Maximum number of hardware rows.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
offset
Number of records to skip before this page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
entity
Participant entity: spine ID, Wikipedia URL or resolved name. Choices: get_parameter_options('epoch_hardware', 'entity').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
participant_role
Source-supported role of the selected entity in the record; distinguish owners, operators, financiers and users. A hardware ownership role does not establish ownership of a building. Choices: get_parameter_options('epoch_hardware', 'participant_role').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description87/100
Epoch AI notable-models catalog — filter by developer (organization), domain, frontier status, or a training-compute floor (min_compute FLOP); sort by publication date or training compute. Each model carries developer, domain, parameters, training hardware + data center, accessibility, and its spine entity_id. START HERE for 'largest / frontier / who trained what' AI-model questions.
The description explains the capability, when to use it, and what to expect.
Inputs90/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
organization_categorization
Substring of the publisher classification of the developing organization; narrows models by that source category. Choices: get_parameter_options('epoch_models', 'organization_categorization').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
organization
Substring match on the developing organization (free text, ~1,300 labs, e.g. OpenAI, Google DeepMind, Anthropic, xAI, Meta AI). No enumerate tool — resolve a canonical lab/org via unified_entity_search(q='OpenAI', type='organization'). Alias: org. Choices: get_parameter_options('epoch_models', 'organization').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
frontier
true → only models Epoch flags as frontier; false → only non-frontier models. Omit for all.
Clear enough to supply this argument.
domain
Task domain (substring-matched against the model's domain list, so one token matches multi-domain models). Choices: get_parameter_options('epoch_models', 'domain').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
model_accessibility
How the publisher makes the model available, distinguishing weights, API access and restricted or unreleased access.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
min_compute
Floor on training_compute_flop, e.g. 1e25 (largest runs) or 1e26 (frontier tier).
Clear enough to supply this argument.
date_start
Publication-date window start YYYY-MM-DD (filters on publication_date).
Clear enough to supply this argument.
date_end
Publication-date window end YYYY-MM-DD (filters on publication_date).
Clear enough to supply this argument.
sort
'compute' sorts by training_compute_flop desc; 'publication_date' (default) sorts newest first.
Clear enough to supply this argument.
limit
Maximum number of models.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
offset
Number of records to skip before this page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
entity
Participant entity: spine ID, Wikipedia URL or resolved name. Choices: get_parameter_options('epoch_models', 'entity').
Clear enough to supply this argument.
participant_role
Source-supported role of the selected entity in the record; distinguish owners, operators, financiers and users. A hardware ownership role does not establish ownership of a building. Choices: get_parameter_options('epoch_models', 'participant_role').
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description86/100
Read typed Epoch AI supporting source observations, including dated finance, cooling, quantity and timeline records. Use for source detail behind AI models, companies and infrastructure; choose a collection from returned rows or the coverage catalog. Filter by participant entity/role, country or name substring q; follow cursor pagination. Preserve native fields, units, periods, qualifiers, uncertainty and measured coverage; missing records are unknown.
The description explains the capability, when to use it, and what to expect.
Inputs94/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
entity
Participant entity: spine id, news id, Wikipedia URL or resolved name. Unresolved names return 404. Choices: get_parameter_options('epoch_observations', 'entity').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
participant_role
Source-supported role of the selected entity in the record; distinguish owners, operators, financiers and users. A hardware ownership role does not establish ownership of a building. Choices: get_parameter_options('epoch_observations', 'participant_role').
Clear enough to supply this argument.
collection
Source collection identifier returned by these observations or the coverage catalog; narrows to that dataset collection. Choices: get_parameter_options('epoch_observations', 'collection').
Clear enough to supply this argument.
country
Exact ISO-3 country when the source reports one. Choices: get_parameter_options('epoch_observations', 'country').
Clear enough to supply this argument.
q
Substring of the observation name.
Clear enough to supply this argument.
limit
Number of records to return on this page; use the returned continuation to request the next page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description86/100
USGS mineral statistics with shared country/region/continent filters. Commodity and statistic are observed suggestions, not closed allowlists. include_summary adds full-filter counts and facets in meta.summary; numeric values remain atomic by source, year, unit, statistic and material. Country reserves are independent of facility capacity. Use for comparable commodity/year/stage/basis observations. Ore is not contained metal; mine, smelter and refinery stages must not be added together. Production/reserves are not current available supply.
The description explains the capability, when to use it, and what to expect.
Inputs94/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
source
Contributing publisher/source identifier from the returned records or source catalog.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
country
Country name, ISO-2 or ISO-3; comma-separated inputs are allowed. Geography filters select country-scoped rows only. Choices: get_parameter_options('resource_statistics', 'country').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
country_iso3
Country name or ISO country code for country-scoped source observations; comma-separated countries are combined as alternatives. Choices: get_parameter_options('resource_statistics', 'country_iso3').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
region
Geographic region whose member countries define the scope.
Clear enough to supply this argument.
continent
Continent whose member countries define the geographic scope.
Clear enough to supply this argument.
commodity
Exact normalized commodity key; observed suggestions are open and not an allowlist. Aggregate rare-earth oxides differ from individual elements. Choices: get_parameter_options('resource_statistics', 'commodity').
Clear enough to supply this argument.
statistic
Exact source statistic name; observed suggestions are open and not an allowlist. Choices: get_parameter_options('resource_statistics', 'statistic').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
statistic_detail
Native source qualifier for a statistic; use the returned statistic_detail to distinguish observations with the same statistic name. Choices: get_parameter_options('resource_statistics', 'statistic_detail').
Clear enough to supply this argument.
material_type
Source-reported kind of material represented by the statistic; copy the returned material_type when narrowing observations. Choices: get_parameter_options('resource_statistics', 'material_type').
Clear enough to supply this argument.
material_form
Source-reported form of the material, such as an ore or refined product; copy the returned material_form. Choices: get_parameter_options('resource_statistics', 'material_form').
Clear enough to supply this argument.
scope
country, aggregate or unresolved source scope.
Clear enough to supply this argument.
year
Source reference year.
Clear enough to supply this argument.
include_summary
Include count-only aggregates for the full filtered result before pagination. Values are never summed across sources, years or units.
Clear enough to supply this argument.
limit
Number of records to return on this page; use the returned continuation to request the next page.
Clear enough to supply this argument.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description93/100
Find facilities with source-reported ownership links to one resolved entity. Resolve its entity_id via unified_entity_search, then optionally scope by type / country / geo. Source coverage, unresolved identities and pagination limit this inventory; it is not a complete legal portfolio. Retain returned ownership evidence and unknown stakes. Ownership does not establish control or operation; for operators use facilities_search with participant_entity and participant_role='operator'.
The description explains the capability, when to use it, and what to expect.
Inputs90/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
owner_entity_id
Resolved entity_id (e_...) with source-reported ownership links. Resolve via unified_entity_search or read owners[].entity_id from a facilities_search card. For operators use facilities_search with participant_entity and participant_role='operator'. Source coverage and pagination apply. Choices: get_parameter_options('facilities_by_owner', 'owner_entity_id').
Clear enough to supply this argument.
q
Facility name. Default lexical mode keeps case-insensitive substring matching. Opt-in search_mode=fuzzy suggests names with matching prefixes or small spelling errors; every query token must match a name token. These are selectable candidates, not resolved site identity. No embedding or inference runs.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
search_mode
lexical (default) preserves substring search. fuzzy requires 2–200 characters and 1–12 name tokens; small typos and token prefixes are supported. Use sort=relevance to put literal matches before fuzzy suggestions. Other category/geography filters stay exact.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
type
Optionally scope the owner's portfolio to one or more facility types.
Clear enough to supply this argument.
country
One or more country filters to scope the owner's portfolio. For a single country pass a one-element list. Choices: get_parameter_options('facilities_by_owner', 'country').
Clear enough to supply this argument.
region
Geographic region whose member countries define the scope.
Clear enough to supply this argument.
continent
Continent whose member countries define the geographic scope.
Clear enough to supply this argument.
has_geo
true → only mappable facilities (with coordinates).
Clear enough to supply this argument.
sort
Facility sort order.
Explain the meaning of this value, not just its name.
limit
Facility cards per page; page with `cursor`.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description93/100
Facility plus bounded owner/parent news context. coverage_paths names each typed relationship, stake and source; minority ownership does not establish control. News is about the named entities, not necessarily located at or affecting the facility. NULL means unavailable; summaries count the returned preview. Name-only owners have separate reported_owner_matches and reported_owner_events/stories from unique exact reference-name or alias discovery. This does not verify ownership or alter resolved owner_events; inspect meta.reported_owner_coverage for measured/partial name scope. Optional include=nearby adds a separately labeled geographic screen with coordinate precision and reporting date coverage; proximity is not a confirmed site incident. Optional gov degrades when unentitled or the scope has multiple entities. Existing can_use_facilities gate and shared REST quotas apply. Use to join a canonical physical site, source participants and nearby reporting; proximity does not prove operational impact.
The description explains the capability, when to use it, and what to expect.
Inputs78/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
facility_id
Canonical facility identifier returned by facilities_search or unified_entity_search; reuse the selected facility ID. Choices: get_parameter_options('facilities_context', 'facility_id').
Clear enough to supply this argument.
days
Owner-coverage window in days, max 30.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
date_start
Explicit start of the owner-coverage window.
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
date_end
Explicit end of the owner-coverage window.
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
limit
Number of owner-linked Events to attach to this facility context.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
include
Optional extra blocks. `gov` attaches the owner's federal-award / FARA / sanctions footprint. An unentitled plan degrades the block to null with a `sources_unavailable` entry — it never 403s the whole response. `nearby` attaches Events within radius_km and their linked Stories. Nearby reporting is a geographic lead, not a confirmed incident at the site. Choices: get_parameter_options('facilities_context', 'include').
Clear enough to supply this argument.
radius_km
Distance in kilometres for optional nearby Event screening. Source coordinate precision is disclosed; nearby reporting is a lead, not a confirmed incident at the facility.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description95/100
Full facility record by facility_id (from a facilities_search card) — identity, type/class, source silo, country + coordinates, owners (names + spine entity_ids), status, capacity, and reversible cross-silo merge history. Native capacity values keep their units; multi-unit sites do not imply a summed total, and missing values remain null. Follow with facilities_context for owner/parent news context.
The description explains the capability, when to use it, and what to expect.
Inputs89/100
Input documentation gives an agent enough context to populate the arguments.
facility_id
The facility's stable id from a facilities_search card (e.g. 'f_1a2b3c4d5e6f7a8b'). Returns the full facility record + reversible cross-silo merge history. Choices: get_parameter_options('facilities_get', 'facility_id').
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description85/100
Native facility observations with dates, units, material basis and shared-capacity groups. Values are not additive totals. Use for unit-level capacity/status and source facts. A site's card capacity may describe one unit; do not treat it as an additive site total or available supply.
The description explains the capability, when to use it, and what to expect.
Inputs79/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
facility_id
Canonical facility identifier returned by facilities_search or unified_entity_search; reuse the selected facility ID. Choices: get_parameter_options('facilities_observations', 'facility_id').
Clear enough to supply this argument.
source
Contributing publisher/source identifier from the returned records or source catalog.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description84/100
Page the selected facility's evidence-backed physical hierarchy in data and source-reported participant assertions in participants. Each collection has independent pagination: links use pagination.next_cursor; participants use meta.participant_pagination.next_cursor. Unresolved identities and claim status remain explicit. Physical hierarchy does not establish common ownership; deep compute and finance observations are separately gated.
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
facility_id
Canonical facility identifier returned by facilities_search or unified_entity_search; reuse the selected facility ID. Choices: get_parameter_options('facilities_relationships', 'facility_id').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
claim_status
Filter assertion status. Default includes reported, probable and verified; unresolved can be requested explicitly. Claim confidence is independent of identity resolution. Choices: get_parameter_options('facilities_relationships', 'claim_status').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
limit
Number of records to return on this page; use the returned continuation to request the next page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description93/100
Search the unified facilities directory — GEM energy assets (plants, mines, terminals, pipelines), mineral and industrial facilities, data centers, and ports. Reviewed fusion retains source memberships and unit observations. Filter by name, leaf type (coal_plant, lng_terminal, port, data_center, …) or coarse class (power/extraction/transport_logistics/digital_infrastructure), source silo, country/region/continent, commodity, owner, source-reported participant entity and exact participant role, status, capacity (MW), and geography (bbox/near). Participant roles are open-vocabulary source assertions, separate from ownership; matching cards retain bounded evidence and disclose truncation. sort=news_activity ranks by direct-owner Events first, then the distinct owner/nearby Event union over seven recent served days and 25 km. Read card.news_activity and meta.news_activity; owner and nearby counts overlap, and nearby reporting does not establish site impact. Multi-unit capacity_mw is not a site total; first/last_seen are observation dates, not source vintage or live uptime. Use returned url for public facility links; dataset credits are attribution. START HERE for 'which facilities are near / owned by / of type X'.
The description explains the capability, when to use it, and what to expect.
Inputs92/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
granularity
site returns canonical physical sites; unit exposes source registry records.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
q
Facility name. Default lexical mode keeps case-insensitive substring matching. Opt-in search_mode=fuzzy suggests names with matching prefixes or small spelling errors; every query token must match a name token. These are selectable candidates, not resolved site identity. No embedding or inference runs.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
search_mode
lexical (default) preserves substring search. fuzzy requires 2–200 characters and 1–12 name tokens; small typos and token prefixes are supported. Use sort=relevance to put literal matches before fuzzy suggestions. Other category/geography filters stay exact.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
type
One or more leaf facility types from this schema, including mineral_mine, mineral_processing_plant, manufacturing_factory and data_center. Omit for all types. Choices: get_parameter_options('facilities_search', 'type').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
facility_class
Coarse class filter, sent to REST as `class`. Read this schema's enum for power, extraction, mineral_processing, manufacturing and the other supported classes.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
source
Contributing source memberships from this schema. A matching canonical site retains all its source observations. Read meta.coverage for published vintages and source-specific geography and participant coverage. Choices: get_parameter_options('facilities_search', 'source').
Clear enough to supply this argument.
country
One or more plain-English country names or ISO-3 codes; matches the facility's primary or secondary country. For a single country pass a one-element list. Choices: get_parameter_options('facilities_search', 'country').
Clear enough to supply this argument.
region
One plain-English region (Middle East, Europe, South Asia, …). Expanded to its ISO-3 country list and applied the same way as `country`.
Clear enough to supply this argument.
continent
One plain-English continent (Asia, Europe, Africa, North America, South America, Oceania). Expanded to its ISO-3 country list and applied the same way as `country`.
Clear enough to supply this argument.
owner_entity_id
Resolved entity_id (e_...) with source-reported ownership links. Resolve via unified_entity_search. For operation use participant_entity with participant_role='operator'; ownership does not establish control or operation. Choices: get_parameter_options('facilities_search', 'owner_entity_id').
Clear enough to supply this argument.
owner_search
Substring match on the owner name (case-insensitive), e.g. 'Aramco', 'Iberdrola'. For an exact owner join use owner_entity_id. Choices: get_parameter_options('facilities_search', 'owner_search').
Clear enough to supply this argument.
entity
Canonical shared entity selector for a facility owner; accepts a terminal spine id or resolvable name. Choices: get_parameter_options('facilities_search', 'entity').
Match a resolved entity named in a source facility participant record; this is separate from owner filters and does not establish ownership. Choices: get_parameter_options('facilities_search', 'participant_entity').
Clear enough to supply this argument.
participant_role
Exact source-reported role in open vocabulary, for example operator or tenant; a role assertion does not establish ownership. Choices: get_parameter_options('facilities_search', 'participant_role').
Clear enough to supply this argument.
status
One or more operating-status values (case-insensitive), e.g. operating, construction, proposed, retired, cancelled. Vocab varies by silo. Choices: get_parameter_options('facilities_search', 'status').
Clear enough to supply this argument.
capacity_mw_min
Minimum capacity in MW (power facilities + data centers carry MW; ports/pipelines/extraction do not and are excluded when this is set).
Clear enough to supply this argument.
capacity_mw_max
Maximum capacity in MW; see capacity_mw_min.
Clear enough to supply this argument.
has_geo
true → facilities with both latitude and longitude; false → facilities missing either. Read geo_precision and geo_evidence before interpreting a point.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
has_owner
true → only facilities with a resolved spine owner (excludes maritime ports, which carry no owner); false → only those without.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
bbox
Geographic viewport 'lat_min,lon_min,lat_max,lon_max'. Returns facilities with coordinates inside the box (geo-null facilities excluded).
Clear enough to supply this argument.
near
Proximity query 'lat,lon,radius_km'. Returns facilities within the radius of a point — use for 'facilities near this event location'.
Clear enough to supply this argument.
sort
'name' | 'capacity_desc' (largest MW first) | 'capacity_asc' | 'recent' (directory updates) | 'country' | 'relevance' (requires q; literal names before fuzzy candidates) | 'news_activity' (seven recent served days: direct-owner Events first, then distinct owner/nearby Events within 25 km; see returned counts and meta.news_activity). Nearby reporting is not a site incident.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
limit
Facility cards per page. Page deeper with `cursor` (the previous response's pagination.next_cursor).
Clear enough to supply this argument.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description97/100
Media tone toward a RESOLVED entity over time — mean tone on a -100..100 scale (negative = critical/adversarial coverage, positive = favorable), with the article/source coverage behind it. The headline `tone_score` BLENDS news coverage with (on some entity-days) recent Bluesky posts; the PRESS-only reading is `news_tone_score` and the social-only one is `social_tone_score`, reported side by side on rows[], entity_coverage[], evidence_samples[] and language_breakdown[]. Quote news_tone_score, not the headline, for a claim about press coverage. NOT public opinion, sentiment polling, or approval, and distinct from risk. Missing evidence is unavailable, not neutral — empty buckets mean no measured coverage, never a 0 reading, and a NULL component means NOT MEASURED (that source contributed no evidence, or the score predates the 2026-08-22 split and cannot be backfilled); 0 is the middle of the band. Read each component against its own denominator — `scored_news_story_count` / `scored_social_story_count` (and `news_article_count` / `social_article_count` per language, `news_evidence_count` / `social_evidence_count` per sample). Social is attached only to entities already in the news stream and never scored alone, so it backs a small minority of scored stories: a social tone quoted without its story count is a misreport. Pass `languages` (e.g. ['ar','zh','en']) to compare how the same entity is covered across language spheres. Start from a name with `entity` (it resolves) or a known `entity_id`.
The description explains the capability, when to use it, and what to expect.
Inputs91/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
entity
Entity to measure tone for, by name (e.g. 'Nvidia') or Wikipedia-keyed id. Resolved to a canonical entity before measuring; pass the name here when you don't already have an id. Either entity or entity_id is required. Choices: get_parameter_options('entity_tone', 'entity').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
entity_id
Known v2/canonical Entity id (from unified_entity_search or get_entity). Use instead of entity when you already have the resolved id. Either entity or entity_id is required. Choices: get_parameter_options('entity_tone', 'entity_id').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
start_date
Inclusive start date in YYYY-MM-DD for the tone window. With end_date, defines a window of at most 30 days. Sent as start_date (this route reads start_date/start, not date_start).
Clear enough to supply this argument.
end_date
Inclusive end date in YYYY-MM-DD for the tone window. With days only, start_date is the trailing window ending here. Defaults to today UTC.
Clear enough to supply this argument.
days
Trailing window size in days, used only to complete the range when start_date or end_date is omitted.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
languages
ISO source-language filter, e.g. ['ar','zh','en']. Restricts the tone timeline + coverage to articles in those source languages so you can compare how an entity is covered across language spheres. Omit for all languages. Choices: get_parameter_options('entity_tone', 'languages').
Clear enough to supply this argument.
include_evidence
When true, attach a sample of the underlying scored articles (the evidence behind each tone reading) so the number is auditable rather than a bare score.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
Align the output schema with the tool’s documented result.
View output schema
{
"if": {
"required": [
"_mcp_projection"
]
},
"else": {
"type": "object",
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"languages": {
"type": "array",
"items": {
"type": "string"
}
},
"bucket_date": {
"type": "string"
},
"entity_type": {
"type": "string"
},
"display_name": {
"type": "string"
},
"avg_confidence": {
"type": "number"
},
"avg_risk_score": {
"type": "number"
},
"avg_tone_score": {
"type": "number"
},
"coverage_ratio": {
"type": "number",
"description": "Share of candidate stories that produced a scored tone row, from 0 to 1. Read this before presenting the aggregate as representative."
},
"agreement_score": {
"type": "number",
"description": "Evidence agreement from 0 to 1: higher values mean the independent evidence items frame the entity more consistently; lower values mean mixed or conflicting framing."
},
"denominator_hash": {
"type": "string"
},
"bucket_granularity": {
"type": "string"
},
"needs_review_count": {
"type": "integer"
},
"scored_story_count": {
"type": "integer"
},
"avg_news_tone_score": {
"type": [
"number",
"null"
],
"description": "Story-weighted mean tone over the NEWS evidence only, for this entity-day. null when no scored story that day carries a news reading — either the evidence was all social, or the day was scored before the split shipped (2026-08-22). Never read null as neutral: 0 is the middle of the band."
},
"canonical_entity_id": {
"type": "string"
},
"top_risky_story_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"scored_article_count": {
"type": "integer"
},
"avg_social_tone_score": {
"type": [
"number",
"null"
],
"description": "Story-weighted mean tone over the BLUESKY SOCIAL evidence only, for this entity-day. Not capped by avg_tone_score — where the two diverge sharply, that gap is the finding. null when not measured."
},
"candidate_story_count": {
"type": "integer"
},
"top_negative_story_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"top_positive_story_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"scored_news_story_count": {
"type": "integer",
"description": "Scored stories that day carrying a news reading. This is the DENOMINATOR of avg_news_tone_score; it is not scored_story_count."
},
"scored_social_story_count": {
"type": "integer",
"description": "Scored stories that day carrying a social reading. Normally a small fraction of scored_story_count — social is attached only to entities already in the news stream. Read avg_social_tone_score against this, not against the headline."
},
"insufficient_evidence_count": {
"type": "integer"
}
}
}
},
"status": {
"type": "string"
},
"end_date": {
"type": "string"
},
"entities": {
"type": "array",
"items": {
"type": "string"
}
},
"start_date": {
"type": "string"
},
"methodology": {
"type": "object",
"properties": {
"unit": {
"type": "string"
},
"risk_score": {
"type": "string"
},
"tone_score": {
"type": "string"
},
"missing_tone": {
"type": "string"
},
"news_tone_score": {
"type": "string"
},
"social_tone_score": {
"type": "string"
}
}
},
"entity_coverage": {
"type": "array",
"items": {
"type": "object",
"properties": {
"row_count": {
"type": "integer"
},
"entity_type": {
"type": "string"
},
"tone_status": {
"type": "string"
},
"display_name": {
"type": "string"
},
"wikipedia_url": {
"type": "string"
},
"mean_news_tone": {
"type": [
"number",
"null"
],
"description": "The entity’s news-only tone over the whole window, weighted by scored_news_story_count. null when not measured."
},
"mean_social_tone": {
"type": [
"number",
"null"
],
"description": "The entity’s social-only tone over the whole window, weighted by scored_social_story_count. null when not measured."
},
"scored_story_count": {
"type": "integer"
},
"canonical_entity_id": {
"type": "string"
},
"candidate_story_count": {
"type": "integer"
},
"candidate_article_count": {
"type": "integer"
},
"candidate_mention_count": {
"type": "integer"
},
"scored_news_story_count": {
"type": "integer",
"description": "Scored stories in the window carrying a news reading — the denominator of mean_news_tone."
},
"scored_social_story_count": {
"type": "integer",
"description": "Scored stories in the window carrying a social reading — the denominator of mean_social_tone."
}
}
}
},
"evidence_samples": {
"type": "array",
"items": {
"type": "object",
"properties": {
"rationale": {
"type": "string"
},
"cluster_id": {
"type": "string"
},
"confidence": {
"type": "number"
},
"risk_label": {
"type": "string"
},
"risk_score": {
"type": "number"
},
"tone_label": {
"type": "string",
"description": "Human-readable band for tone_score. Null whenever tone_score is unavailable."
},
"tone_score": {
"type": "number",
"description": "Blended media-framing score from -100 (most negative) to 100 (most positive). Null means the story was not scored; 0 is a measured neutral reading."
},
"story_title": {
"type": "string"
},
"display_name": {
"type": "string"
},
"score_status": {
"type": "string"
},
"evidence_uids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Index-aligned with evidence_snippets. A \"bluesky:\" prefix marks a social item."
},
"conflict_label": {
"enum": [
"aligned",
"mixed",
"conflicting",
"insufficient"
],
"type": "string",
"description": "Qualitative evidence-agreement band. `aligned` means consistent framing; `mixed` means material variation; `conflicting` means opposing readings; `insufficient` means there was not enough independent evidence to assess agreement."
},
"agreement_score": {
"type": "number",
"description": "Evidence agreement from 0 to 1: higher values mean the independent evidence items frame the entity more consistently; lower values mean mixed or conflicting framing."
},
"canonical_title": {
"type": "string",
"description": "English-preferred headline for the story; falls back to the representative title."
},
"evidence_titles": {
"type": "array",
"items": {
"type": "string"
}
},
"news_tone_label": {
"type": [
"string",
"null"
],
"description": "Band name for news_tone_score."
},
"news_tone_score": {
"type": [
"number",
"null"
],
"description": "Tone over this story’s NEWS evidence only. null when the story carried no news evidence for this entity (news_evidence_count = 0) or was scored before 2026-08-22."
},
"latest_scored_at": {
"type": "string"
},
"cluster_date_text": {
"type": "string"
},
"evidence_snippets": {
"type": "array",
"items": {
"type": "string"
},
"description": "Up to 4 quoted snippets the model read."
},
"social_tone_label": {
"type": [
"string",
"null"
],
"description": "Band name for social_tone_score."
},
"social_tone_score": {
"type": [
"number",
"null"
],
"description": "Tone over this story’s BLUESKY SOCIAL evidence only. null when the story carried no social evidence (social_evidence_count = 0) or was scored before 2026-08-22."
},
"evidence_languages": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"canonical_entity_id": {
"type": "string"
},
"news_evidence_count": {
"type": "integer",
"description": "Evidence items behind news_tone_score. Together with social_evidence_count this tells a null \"no evidence of this kind\" apart from a null \"scored before the split\"."
},
"evidence_source_urls": {
"type": "array",
"items": {
"type": "string"
},
"description": "Index-aligned permalinks. EMPTY means not recorded (scored before 2026-08 attribution), never \"no source\"."
},
"evidence_source_count": {
"type": "integer"
},
"social_evidence_count": {
"type": "integer",
"description": "Evidence items behind social_tone_score."
},
"evidence_article_count": {
"type": "integer"
},
"evidence_snippet_count": {
"type": "integer"
}
}
},
"description": "One card per scored story, returned when include_evidence=true. Capped by evidence_limit."
},
"unresolved_terms": {
"type": "array",
"items": {}
},
"resolved_entities": {
"type": "array",
"items": {
"type": "object",
"properties": {
"input": {
"type": "string"
},
"match_type": {
"type": "string"
},
"entity_type": {
"type": "string"
},
"display_name": {
"type": "string"
},
"wikipedia_url": {
"type": "string"
},
"canonical_entity_id": {
"type": "string"
}
}
}
},
"language_breakdown": {
"type": "array",
"items": {
"type": "object",
"properties": {
"language": {
"type": "string"
},
"scored_rows": {
"type": "integer",
"description": "Scored (entity, story) rows contributing to this language."
},
"article_count": {
"type": "integer",
"description": "All evidence items in this language."
},
"avg_tone_score": {
"type": [
"number",
"null"
],
"description": "Blended tone for stories covered in this language, weighted by that language’s evidence-item count."
},
"news_article_count": {
"type": "integer",
"description": "Evidence items in this language behind avg_news_tone_score."
},
"avg_news_tone_score": {
"type": [
"number",
"null"
],
"description": "News-only tone for this language, weighted by news_article_count. null when no news evidence in this language carries a reading."
},
"social_article_count": {
"type": "integer",
"description": "Evidence items in this language behind avg_social_tone_score."
},
"avg_social_tone_score": {
"type": [
"number",
"null"
],
"description": "Social-only tone for this language, weighted by social_article_count. null when none — never 0."
}
}
},
"description": "Tone per evidence language over the FULL scored window (not the evidence sample), split by evidence source."
}
}
},
"then": {
"type": "object",
"required": [
"_mcp_projection"
],
"properties": {
"rows": {
"type": "array"
},
"status": {
"type": "string"
},
"end_date": {
"type": "string"
},
"entities": {
"type": "array"
},
"start_date": {
"type": "string"
},
"methodology": {
"type": "object"
},
"_mcp_projection": {
"type": "object",
"required": [
"mode"
],
"properties": {
"mode": {
"const": "compact"
},
"truncated": {
"type": "boolean"
}
},
"description": "Explicitly discloses omitted fields or shortened evidence."
},
"entity_coverage": {
"type": "array"
},
"evidence_samples": {
"type": "array"
},
"unresolved_terms": {
"type": "array"
},
"resolved_entities": {
"type": "array"
},
"language_breakdown": {
"type": "array"
}
}
},
"type": "object",
"description": "Full preserves the bounded API response. Compact preserves evidence, coverage, filters and pagination with explicit projection disclosure; neither fetches other pages."
}
Original tool metadata
{
"name": "entity_tone",
"title": "Media Intelligence: entity tone",
"description": "Media tone toward a RESOLVED entity over time — mean tone on a -100..100 scale (negative = critical/adversarial coverage, positive = favorable), with the article/source coverage behind it. The headline `tone_score` BLENDS news coverage with (on some entity-days) recent Bluesky posts; the PRESS-only reading is `news_tone_score` and the social-only one is `social_tone_score`, reported side by side on rows[], entity_coverage[], evidence_samples[] and language_breakdown[]. Quote news_tone_score, not the headline, for a claim about press coverage. NOT public opinion, sentiment polling, or approval, and distinct from risk. Missing evidence is unavailable, not neutral — empty buckets mean no measured coverage, never a 0 reading, and a NULL component means NOT MEASURED (that source contributed no evidence, or the score predates the 2026-08-22 split and cannot be backfilled); 0 is the middle of the band. Read each component against its own denominator — `scored_news_story_count` / `scored_social_story_count` (and `news_article_count` / `social_article_count` per language, `news_evidence_count` / `social_evidence_count` per sample). Social is attached only to entities already in the news stream and never scored alone, so it backs a small minority of scored stories: a social tone quoted without its story count is a misreport. Pass `languages` (e.g. ['ar','zh','en']) to compare how the same entity is covered across language spheres. Start from a name with `entity` (it resolves) or a known `entity_id`.",
"inputSchema": {
"type": "object",
"properties": {
"days": {
"type": "integer",
"default": 7,
"maximum": 30,
"minimum": 1,
"description": "Trailing window size in days, used only to complete the range when start_date or end_date is omitted."
},
"entity": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Entity to measure tone for, by name (e.g. 'Nvidia') or Wikipedia-keyed id. Resolved to a canonical entity before measuring; pass the name here when you don't already have an id. Either entity or entity_id is required. Choices: get_parameter_options('entity_tone', 'entity').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "identifier",
"enum_id": "entity_handle",
"parameter": "entity"
}
},
"end_date": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Inclusive end date in YYYY-MM-DD for the tone window. With days only, start_date is the trailing window ending here. Defaults to today UTC."
},
"entity_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Known v2/canonical Entity id (from unified_entity_search or get_entity). Use instead of entity when you already have the resolved id. Either entity or entity_id is required. Choices: get_parameter_options('entity_tone', 'entity_id').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "identifier",
"parameter": "entity_id"
}
},
"languages": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"default": null,
"description": "ISO source-language filter, e.g. ['ar','zh','en']. Restricts the tone timeline + coverage to articles in those source languages so you can compare how an entity is covered across language spheres. Omit for all languages. Choices: get_parameter_options('entity_tone', 'languages').",
"x-gdelt-options": {
"tool": "get_parameter_options",
"space": "observed",
"enum_id": "coverage_language",
"parameter": "languages"
}
},
"start_date": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Inclusive start date in YYYY-MM-DD for the tone window. With end_date, defines a window of at most 30 days. Sent as start_date (this route reads start_date/start, not date_start)."
},
"response_mode": {
"enum": [
"compact",
"full"
],
"type": "string",
"default": "compact",
"description": "Compact chat projection or unchanged bounded full API response; neither fetches another page."
},
"include_evidence": {
"type": "boolean",
"default": false,
"description": "When true, attach a sample of the underlying scored articles (the evidence behind each tone reading) so the number is auditable rather than a bare score."
}
},
"additionalProperties": false
},
"outputSchema": {
"if": {
"required": [
"_mcp_projection"
]
},
"else": {
"type": "object",
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"languages": {
"type": "array",
"items": {
"type": "string"
}
},
"bucket_date": {
"type": "string"
},
"entity_type": {
"type": "string"
},
"display_name": {
"type": "string"
},
"avg_confidence": {
"type": "number"
},
"avg_risk_score": {
"type": "number"
},
"avg_tone_score": {
"type": "number"
},
"coverage_ratio": {
"type": "number",
"description": "Share of candidate stories that produced a scored tone row, from 0 to 1. Read this before presenting the aggregate as representative."
},
"agreement_score": {
"type": "number",
"description": "Evidence agreement from 0 to 1: higher values mean the independent evidence items frame the entity more consistently; lower values mean mixed or conflicting framing."
},
"denominator_hash": {
"type": "string"
},
"bucket_granularity": {
"type": "string"
},
"needs_review_count": {
"type": "integer"
},
"scored_story_count": {
"type": "integer"
},
"avg_news_tone_score": {
"type": [
"number",
"null"
],
"description": "Story-weighted mean tone over the NEWS evidence only, for this entity-day. null when no scored story that day carries a news reading — either the evidence was all social, or the day was scored before the split shipped (2026-08-22). Never read null as neutral: 0 is the middle of the band."
},
"canonical_entity_id": {
"type": "string"
},
"top_risky_story_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"scored_article_count": {
"type": "integer"
},
"avg_social_tone_score": {
"type": [
"number",
"null"
],
"description": "Story-weighted mean tone over the BLUESKY SOCIAL evidence only, for this entity-day. Not capped by avg_tone_score — where the two diverge sharply, that gap is the finding. null when not measured."
},
"candidate_story_count": {
"type": "integer"
},
"top_negative_story_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"top_positive_story_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"scored_news_story_count": {
"type": "integer",
"description": "Scored stories that day carrying a news reading. This is the DENOMINATOR of avg_news_tone_score; it is not scored_story_count."
},
"scored_social_story_count": {
"type": "integer",
"description": "Scored stories that day carrying a social reading. Normally a small fraction of scored_story_count — social is attached only to entities already in the news stream. Read avg_social_tone_score against this, not against the headline."
},
"insufficient_evidence_count": {
"type": "integer"
}
}
}
},
"status": {
"type": "string"
},
"end_date": {
"type": "string"
},
"entities": {
"type": "array",
"items": {
"type": "string"
}
},
"start_date": {
"type": "string"
},
"methodology": {
"type": "object",
"properties": {
"unit": {
"type": "string"
},
"risk_score": {
"type": "string"
},
"tone_score": {
"type": "string"
},
"missing_tone": {
"type": "string"
},
"news_tone_score": {
"type": "string"
},
"social_tone_score": {
"type": "string"
}
}
},
"entity_coverage": {
"type": "array",
"items": {
"type": "object",
"properties": {
"row_count": {
"type": "integer"
},
"entity_type": {
"type": "string"
},
"tone_status": {
"type": "string"
},
"display_name": {
"type": "string"
},
"wikipedia_url": {
"type": "string"
},
"mean_news_tone": {
"type": [
"number",
"null"
],
"description": "The entity’s news-only tone over the whole window, weighted by scored_news_story_count. null when not measured."
},
"mean_social_tone": {
"type": [
"number",
"null"
],
"description": "The entity’s social-only tone over the whole window, weighted by scored_social_story_count. null when not measured."
},
"scored_story_count": {
"type": "integer"
},
"canonical_entity_id": {
"type": "string"
},
"candidate_story_count": {
"type": "integer"
},
"candidate_article_count": {
"type": "integer"
},
"candidate_mention_count": {
"type": "integer"
},
"scored_news_story_count": {
"type": "integer",
"description": "Scored stories in the window carrying a news reading — the denominator of mean_news_tone."
},
"scored_social_story_count": {
"type": "integer",
"description": "Scored stories in the window carrying a social reading — the denominator of mean_social_tone."
}
}
}
},
"evidence_samples": {
"type": "array",
"items": {
"type": "object",
"properties": {
"rationale": {
"type": "string"
},
"cluster_id": {
"type": "string"
},
"confidence": {
"type": "number"
},
"risk_label": {
"type": "string"
},
"risk_score": {
"type": "number"
},
"tone_label": {
"type": "string",
"description": "Human-readable band for tone_score. Null whenever tone_score is unavailable."
},
"tone_score": {
"type": "number",
"description": "Blended media-framing score from -100 (most negative) to 100 (most positive). Null means the story was not scored; 0 is a measured neutral reading."
},
"story_title": {
"type": "string"
},
"display_name": {
"type": "string"
},
"score_status": {
"type": "string"
},
"evidence_uids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Index-aligned with evidence_snippets. A \"bluesky:\" prefix marks a social item."
},
"conflict_label": {
"enum": [
"aligned",
"mixed",
"conflicting",
"insufficient"
],
"type": "string",
"description": "Qualitative evidence-agreement band. `aligned` means consistent framing; `mixed` means material variation; `conflicting` means opposing readings; `insufficient` means there was not enough independent evidence to assess agreement."
},
"agreement_score": {
"type": "number",
"description": "Evidence agreement from 0 to 1: higher values mean the independent evidence items frame the entity more consistently; lower values mean mixed or conflicting framing."
},
"canonical_title": {
"type": "string",
"description": "English-preferred headline for the story; falls back to the representative title."
},
"evidence_titles": {
"type": "array",
"items": {
"type": "string"
}
},
"news_tone_label": {
"type": [
"string",
"null"
],
"description": "Band name for news_tone_score."
},
"news_tone_score": {
"type": [
"number",
"null"
],
"description": "Tone over this story’s NEWS evidence only. null when the story carried no news evidence for this entity (news_evidence_count = 0) or was scored before 2026-08-22."
},
"latest_scored_at": {
"type": "string"
},
"cluster_date_text": {
"type": "string"
},
"evidence_snippets": {
"type": "array",
"items": {
"type": "string"
},
"description": "Up to 4 quoted snippets the model read."
},
"social_tone_label": {
"type": [
"string",
"null"
],
"description": "Band name for social_tone_score."
},
"social_tone_score": {
"type": [
"number",
"null"
],
"description": "Tone over this story’s BLUESKY SOCIAL evidence only. null when the story carried no social evidence (social_evidence_count = 0) or was scored before 2026-08-22."
},
"evidence_languages": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"canonical_entity_id": {
"type": "string"
},
"news_evidence_count": {
"type": "integer",
"description": "Evidence items behind news_tone_score. Together with social_evidence_count this tells a null \"no evidence of this kind\" apart from a null \"scored before the split\"."
},
"evidence_source_urls": {
"type": "array",
"items": {
"type": "string"
},
"description": "Index-aligned permalinks. EMPTY means not recorded (scored before 2026-08 attribution), never \"no source\"."
},
"evidence_source_count": {
"type": "integer"
},
"social_evidence_count": {
"type": "integer",
"description": "Evidence items behind social_tone_score."
},
"evidence_article_count": {
"type": "integer"
},
"evidence_snippet_count": {
"type": "integer"
}
}
},
"description": "One card per scored story, returned when include_evidence=true. Capped by evidence_limit."
},
"unresolved_terms": {
"type": "array",
"items": {}
},
"resolved_entities": {
"type": "array",
"items": {
"type": "object",
"properties": {
"input": {
"type": "string"
},
"match_type": {
"type": "string"
},
"entity_type": {
"type": "string"
},
"display_name": {
"type": "string"
},
"wikipedia_url": {
"type": "string"
},
"canonical_entity_id": {
"type": "string"
}
}
}
},
"language_breakdown": {
"type": "array",
"items": {
"type": "object",
"properties": {
"language": {
"type": "string"
},
"scored_rows": {
"type": "integer",
"description": "Scored (entity, story) rows contributing to this language."
},
"article_count": {
"type": "integer",
"description": "All evidence items in this language."
},
"avg_tone_score": {
"type": [
"number",
"null"
],
"description": "Blended tone for stories covered in this language, weighted by that language’s evidence-item count."
},
"news_article_count": {
"type": "integer",
"description": "Evidence items in this language behind avg_news_tone_score."
},
"avg_news_tone_score": {
"type": [
"number",
"null"
],
"description": "News-only tone for this language, weighted by news_article_count. null when no news evidence in this language carries a reading."
},
"social_article_count": {
"type": "integer",
"description": "Evidence items in this language behind avg_social_tone_score."
},
"avg_social_tone_score": {
"type": [
"number",
"null"
],
"description": "Social-only tone for this language, weighted by social_article_count. null when none — never 0."
}
}
},
"description": "Tone per evidence language over the FULL scored window (not the evidence sample), split by evidence source."
}
}
},
"then": {
"type": "object",
"required": [
"_mcp_projection"
],
"properties": {
"rows": {
"type": "array"
},
"status": {
"type": "string"
},
"end_date": {
"type": "string"
},
"entities": {
"type": "array"
},
"start_date": {
"type": "string"
},
"methodology": {
"type": "object"
},
"_mcp_projection": {
"type": "object",
"required": [
"mode"
],
"properties": {
"mode": {
"const": "compact"
},
"truncated": {
"type": "boolean"
}
},
"description": "Explicitly discloses omitted fields or shortened evidence."
},
"entity_coverage": {
"type": "array"
},
"evidence_samples": {
"type": "array"
},
"unresolved_terms": {
"type": "array"
},
"resolved_entities": {
"type": "array"
},
"language_breakdown": {
"type": "array"
}
}
},
"type": "object",
"description": "Full preserves the bounded API response. Compact preserves evidence, coverage, filters and pagination with explicit projection disclosure; neither fetches other pages."
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
Shorten the title to an action and subject; move usage details into the description.
Description88/100
Share of voice — each entity's share of coverage WITHIN a conversation you define, as a fraction of that conversation's total coverage. You MUST define 'the conversation' (the denominator) with at least one of query/topic/category/country/region/languages/source_set; `query` (a semantic topic description) is the preferred default. `entities` is the numerator. Measures relative PRESS attention, not popularity/sentiment/market share. `languages` scopes the whole conversation (numerator + denominator) to a language sphere for cross-language share-of-voice comparison. Missing evidence is unavailable, not zero.
The description explains the capability, when to use it, and what to expect.
Inputs91/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
entities
Entity identifiers. `entity_id` and `entity` are singular compatibility aliases.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
start_date
Inclusive start date in YYYY-MM-DD for the window. With end_date, defines a window of at most 30 days. Sent as start_date (this route reads start_date/start, not date_start).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
end_date
Inclusive end date in YYYY-MM-DD for the window. With days only, start_date is the trailing window ending here. Defaults to today UTC.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
query
DENOMINATOR (preferred default): a semantic description of 'the conversation' to measure share within, e.g. 'AI accelerator chips' or 'Red Sea shipping disruption'. Embedding-matched, so it captures the topic even when wording varies. Define the denominator with at least one of query/topic/category/country/region/languages/source_set; prefer query.
Clear enough to supply this argument.
topic
DENOMINATOR: a keyword/topic label scoping the conversation. Coarser than semantic query — prefer query unless you need an exact label match. One of the denominator inputs.
Clear enough to supply this argument.
category
DENOMINATOR: Event/coverage categories scoping the conversation, e.g. ['INFRASTRUCTURE','ECONOMIC']. OR'd together. One of the denominator inputs.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
country
DENOMINATOR: countries scoping the conversation (plain English names or ISO-3, e.g. ['United States','CHN']). Limits the denominator coverage to these countries. One of the denominator inputs. Choices: get_parameter_options('share_of_voice', 'country').
Clear enough to supply this argument.
region
DENOMINATOR: regions/continents scoping the conversation (e.g. ['Middle East']), expanded to country coverage. One of the denominator inputs.
Clear enough to supply this argument.
languages
DENOMINATOR: ISO source-language filter for the conversation, e.g. ['ar','zh','en'], so you can measure share of voice within a language sphere. One of the denominator inputs. Choices: get_parameter_options('share_of_voice', 'languages').
Clear enough to supply this argument.
source_set
DENOMINATOR: named source/outlet sets scoping the conversation (e.g. a curated outlet list). One of the denominator inputs. Choices: get_parameter_options('share_of_voice', 'source_set').
Clear enough to supply this argument.
continent
Continent restricting the Story/Event comparison denominator to its geographic coverage.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
date
Anchor date of the comparison window, in YYYY-MM-DD.
Clear enough to supply this argument.
days
Length in days of the trailing comparison window ending at the selected date.
Clear enough to supply this argument.
denominator_hash
Denominator identity returned by a previous share_of_voice computation; reuses that exact comparison baseline.
Clear enough to supply this argument.
entity_query
Entity-name resolver input. `entity_search`, `entity_terms`, and `numerator` are aliases.
Clear enough to supply this argument.
limit
Number of records to return on this page; pagination describes how to continue.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
offset
Legacy number of source-article rows to skip; prefer the continuation cursor for new calls.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
run_id
Materialized analytics run identifier returned by share_of_voice; selects that computation. Choices: get_parameter_options('share_of_voice', 'run_id').
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
Shorten the title to an action and subject; move usage details into the description.
Description90/100
Live Bluesky (AT Protocol) social signal for an entity — recent post mention volume, engagement, sample posts, and an INDICATIVE naive-lexicon sentiment read. A real-time social pulse complementing the news-based entity_tone; NOT a calibrated tone model. Strong for news/politics/companies/policy, thin for granular assets + non-English entities.
The description explains the capability, when to use it, and what to expect.
Inputs87/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
entity
Entity to measure the live Bluesky social signal for, by name (e.g. 'Nvidia'). Searches the full Bluesky (AT Protocol) network for recent posts mentioning it. Choices: get_parameter_options('social_signal', 'entity').
Clear enough to supply this argument.
days
Trailing window in days for recent social mentions.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description97/100
US federal award exposure for an entity — USAspending prime awards (contracts + grants) keyed on SAM.gov UEI and resolved to the entity spine. Returns the award timeline + a per-UEI rollup (count, total obligated, top awarding agencies), each cited to its USAspending permalink. Pass one of entity= (a resolved entity_id — resolve a name via unified_entity_search first; inspect candidates and select the intended identity), uei=, or recipient= (fuzzy name). D&B carve-out: UEI only, never DUNS or the D&B parent tree. Plan-gated (can_use_gov).
The description explains the capability, when to use it, and what to expect.
Inputs80/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
entity
A RESOLVED spine entity_id (e_...). Returns the entity's US federal award timeline + per-UEI rollup. Resolve a name->entity_id via unified_entity_search. Choices: get_parameter_options('gov_awards', 'entity').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
uei
SAM.gov Unique Entity Identifier of an award recipient, returned by gov_awards; use it to select that recipient. Choices: get_parameter_options('gov_awards', 'uei').
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
recipient
Fuzzy recipient-name match (case-insensitive contains), e.g. 'Lockheed', 'SpaceX'. Use when you have no resolved entity_id or UEI.
Clear enough to supply this argument.
limit
Maximum number of awards in the timeline.
Explain what happens when this optional value is omitted.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description90/100
US foreign-influence graph (DOJ FARA) — registrations linking a US registrant (law/lobby/PR firm) to the foreign principal it represents, both resolved to the entity spine. Filter by a resolved entity= (matches EITHER side), a fuzzy registrant=/foreign_principal= name, or country=. The differentiator: sanctioned_only=true returns only links whose foreign principal is on our screening lists (OFAC SDN/BIS Entity/DoD 1260H/OFAC CMIC/UK) with the specific programs — US firms registered as agents for a SANCTIONED entity, not merely an adversary country. Plan-gated (can_use_gov).
The description explains the capability, when to use it, and what to expect.
Inputs96/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
entity
A RESOLVED spine entity_id (e_...). Matches EITHER side of a FARA link (the US registrant OR the foreign principal). Resolve a name->entity_id via unified_entity_search. Choices: get_parameter_options('gov_fara', 'entity').
Clear enough to supply this argument.
registrant
Fuzzy US-registrant name (law/lobby/PR firm), e.g. 'Hogan Lovells', 'Ruder Finn'.
Clear enough to supply this argument.
foreign_principal
Fuzzy foreign-principal name, e.g. 'Huawei', 'PDVSA'.
Clear enough to supply this argument.
country
Country/location represented, as published by FARA (upper-case), e.g. 'RUSSIA', 'CHINA'. Choices: get_parameter_options('gov_fara', 'country').
Clear enough to supply this argument.
sanctioned_only
true -> only links whose foreign principal is on a sanctions/restricted list (OFAC/BIS/1260H/UK) - the 'US firm repping a sanctioned entity' signal.
Clear enough to supply this argument.
adversary_only
true -> only adversary-government links (RU/CN/IR/KP/SY/CU/VE/BY/MM).
Clear enough to supply this argument.
active_only
true -> only still-active registrations (no termination date).
Clear enough to supply this argument.
limit
Maximum number of links returned.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
Shorten the title to an action and subject; move usage details into the description.
Description90/100
Published office evidence with incomplete source/country coverage; preserve undated and unresolved records. Every public office one entity has held, as the publishers assert it — the actor-context complement to get_entity. entity_id accepts a spine e_… id, a news wiki: / llm: id or a wikipedia_url (resolve a name via unified_entity_search first). READ meta.checked: data: [] with checked: true = resolved and holds no office; checked: false = no spine identity to look under, i.e. we did NOT look — never report that as 'holds no office'; an unresolvable ref is 404 ENTITY_NOT_FOUND, never an empty 200. status= / as_of= (VALID TIME, who held office on that date) as on office_holders. Actor context; NOT a PEP or sanctions-screening tool and never a compliance determination.
The description explains the capability, when to use it, and what to expect.
Inputs90/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
entity_id
Resolved entity identifier returned by unified_entity_search or get_entity; selects that person or organization office evidence. Choices: get_parameter_options('entity_offices', 'entity_id').
Clear enough to supply this argument.
status
Office_holders the PUBLISHER asserts as current | ended | unknown (unknown = the source did not say; never inferred from a missing end_date). Independent of as_of.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
as_of
VALID TIME (YYYY-MM-DD): only offices whose published start/end interval covers this date. Not knowledge-time replay; undated office-holders are excluded, never guessed.
Clear enough to supply this argument.
limit
Maximum number of office-holders. No cursor — truncated: true says when the cap bit.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
Shorten the title to an action and subject; move usage details into the description.
Description94/100
Published office evidence with incomplete source/country coverage; preserve undated and unresolved records. One political office by id (Wikidata QID or p_… id from offices_search — a NAME is not looked up here) with a capped preview of its holders ordered current -> ended -> unknown; holders_truncated says when to walk office_holders instead. as_of (YYYY-MM-DD) is VALID TIME — attaches holders_as_of, who held the office ON that date by the publisher's start/end dates; not knowledge-time replay. Actor context; NOT a PEP or sanctions-screening tool.
The description explains the capability, when to use it, and what to expect.
Inputs83/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
office_id
The office id — a Wikidata QID (Q…) or the p_… id offices_search serves. A NAME is not looked up here: resolve it with offices_search first. Choices: get_parameter_options('office_get', 'office_id').
Clear enough to supply this argument.
as_of
VALID TIME (YYYY-MM-DD): attach holders_as_of — how many holders were in office on that date by the publisher's start/end dates — and preview those holders. Not knowledge-time replay; undated office-holders are excluded, never guessed.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Shorten the title to an action and subject; move usage details into the description.
Description92/100
Published office evidence with incomplete source/country coverage; preserve undated and unresolved records. The valid-time roster of one office: every (holder, term) the publishers assert, ordered current -> ended -> unknown, most recent start first. status= is what the PUBLISHER asserts (unknown is a real bucket — never inferred from a missing end_date); as_of= (YYYY-MM-DD) is VALID TIME = who HELD the office on that date, undated office-holders excluded rather than guessed. Resolved holders carry canonical entity IDs; an unresolved holder is served with entity_id: null and its holder_source_ref, never dropped. Keyset cursor; a stale token is 400 CURSOR_STALE. Actor context; NOT a PEP or sanctions-screening tool.
The description explains the capability, when to use it, and what to expect.
Inputs92/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
office_id
The office id — a Wikidata QID (Q…) or the p_… id offices_search serves. Choices: get_parameter_options('office_holders', 'office_id').
Clear enough to supply this argument.
status
Office_holders the PUBLISHER asserts as current | ended | unknown. unknown is a real bucket, not a synonym for current — the source did not say, and nothing infers currency from a missing end_date. Independent of as_of; combine them for 'current AND in office on that date'.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
as_of
VALID TIME (YYYY-MM-DD): only the (holder, term) rows whose published start/end interval covers this date. Not knowledge-time replay. Office_holders with no published start date are excluded (meta.undated_office_holders), never placed by guess.
Clear enough to supply this argument.
limit
Maximum number of office-holders per page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description96/100
Published office evidence with incomplete source/country coverage; preserve undated and unresolved records. Search public political offices — legislative seats, cabinet posts, heads of state and government, courts, security/financial offices, IGO posts — one row per office with holder counts (holders_current is NULL, never 0, when no source asserts currency). Filter by country (ISO-3 / name, OR'd), scope (national | subnational | international), branch (legislative | executive | head | judicial | security | financial | igo | other), organization, has_holders, and as_of. q= is a case-insensitive SUBSTRING over the office name, not semantic search. START HERE to resolve an office name to its id (a Wikidata QID or p_… id) before passing office= to search_events / search_stories, or calling office_get / office_holders. Office-holders are ACTOR CONTEXT for events — NOT a PEP or sanctions-screening tool and never a compliance determination.
The description explains the capability, when to use it, and what to expect.
Inputs92/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
q
Case-insensitive SUBSTRING match over the office name (e.g. 'Minister of Finance', 'Member of Parliament'). Not semantic: a related term that does not appear literally will not match. Results keep the sort order, not relevance — narrow with country.
Clear enough to supply this argument.
country
Country of the office — ISO-3, ISO-2 or a name; several values are OR'd. IGO / supranational posts carry no country and never match a country filter: use scope='international' for those. Choices: get_parameter_options('offices_search', 'country').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
scope
Level of government: national | subnational (state / province / municipality) | international (IGO and supranational posts). An office with no scope topic is served as national.
Clear enough to supply this argument.
branch
Branch of government: legislative | executive | head (head of state / government — wins over executive when both apply) | judicial | security | financial | igo | other (offices whose topics name no recognised branch).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
organization
The legislature / ministry / court the office belongs to. A spine e_… id matches the resolved organization exactly (arbiter family); any other value is a case-insensitive substring on the organization name as published. Choices: get_parameter_options('offices_search', 'organization').
Clear enough to supply this argument.
has_holders
true = offices with at least one office-holder on record (any status); false = offices we know only as an office. Counts office-holders, not asserted currency.
Clear enough to supply this argument.
as_of
VALID TIME (YYYY-MM-DD): restrict to offices with at least one holder IN OFFICE on that date, read from the publisher's start/end dates, and attach holders_as_of to every row. Not knowledge-time replay. Office_holders with no published start date cannot be placed on a date and are EXCLUDED (meta.undated_office_holders counts them), never guessed. A future date reads as 'still in office as far as the source has published'.
Clear enough to supply this argument.
sort
name (default, A-Z) | holders_desc (most office-holders on record first) | country. The cursor is bound to the sort it was minted under — changing sort mid-walk is 400 CURSOR_STALE.
Clear enough to supply this argument.
limit
Maximum number of offices per page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
include_facets
Include complete country facets over the served office registry, independent of pagination and country/name filters. Holder counts are terms across offices, not distinct people. Null facets mean unavailable.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description89/100
An entity's corporate hierarchy — direct parent, ultimate parent, children — resolved through the entity spine. Accepts a NAME, a resolved e_ id, a wiki: id, a wikipedia_url or a bare LEI, so it composes directly off search results without translating ids. ALWAYS read the `coverage` block first: lei_present=false means WE hold no LEI (a coverage gap, not 'no parent'), while a reporting_exception means the filer DECLARED an exception instead of naming one. Not ownership. Gated on can_use_exposure.
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Explain what happens when this optional value is omitted.
entity_id
Entity handle from unified_entity_search or a known LEI. Supports resolved e_, wiki: or llm: IDs, Wikipedia URLs and names; select the intended legal entity first. Choices: get_parameter_options('entity_hierarchy', 'entity_id').
Clear enough to supply this argument.
direction
Traverse reported parent links, child links or both in the corporate hierarchy; these are accounting-consolidation relationships, not ownership percentages.
Explain what happens when this optional value is omitted.
depth
Number of reported direct-parent hops to traverse; a bounded or stopped chain is not proof of a complete hierarchy.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
include_siblings
true -> also return entities sharing the same direct parent.
Clear enough to supply this argument.
limit
Number of children to return from the reported corporate hierarchy.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description96/100
Search the GLEIF Global LEI Index — 3.39M legal entities with registered name, jurisdiction, entity + registration status, legal form and registration authority. At least one filter is REQUIRED (lei/name/country/jurisdiction/entity_status/registration_status/entity_category); an unfiltered call returns 400 FILTER_REQUIRED. `name` is normalized-exact or prefix, never a substring scan. A hit is a legal-entity REGISTRATION and is NOT evidence we hold news coverage for it. CC0. Plan-gated (can_use_gleif). Returns data legal-registration records and pagination/applied_filters; entity status and LEI renewal status describe different facts. A registry hit does not establish news coverage.
The description explains the capability, when to use it, and what to expect.
Inputs91/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
lei
Legal Entity Identifier returned by gleif_entities or an earlier registry result. Reuse that registration identifier. Choices: get_parameter_options('gleif_entities', 'lei').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
name
Legal name - normalized-exact or PREFIX match. Not a substring search, so 'Siemens' matches 'Siemens Aktiengesellschaft' but 'emens' matches nothing.
Clear enough to supply this argument.
country
ISO-3 country of the legal address, e.g. 'DEU', 'USA'. Choices: get_parameter_options('gleif_entities', 'country').
Clear enough to supply this argument.
jurisdiction
GLEIF's raw legal jurisdiction - alpha-2 or subdivision, e.g. 'DE', 'US-DE'. Choices: get_parameter_options('gleif_entities', 'jurisdiction').
Clear enough to supply this argument.
entity_status
Publisher status of the legal entity, separate from whether its LEI registration was renewed.
Clear enough to supply this argument.
registration_status
LEI registration status, e.g. 'ISSUED', 'LAPSED', 'RETIRED'. NOTE a LAPSED registration means the LEI was not renewed - NOT that the company ceased to exist.
Clear enough to supply this argument.
entity_category
Publisher legal-entity category used to distinguish companies, funds, branches and sole proprietors.
Clear enough to supply this argument.
limit
Rows to return.
Explain the meaning of this value, not just its name.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description95/100
One full GLEIF record for a single LEI plus its Level-2 relationships, declared reporting exceptions and LEI↔ISIN mappings. Relationships are corporate hierarchy (accounting consolidation), not ownership. 400 INVALID_LEI if the LEI fails the ISO 17442 check digit; 404 if it is well-formed but absent from the index. Plan-gated (can_use_gleif).
The description explains the capability, when to use it, and what to expect.
Inputs86/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
lei
Legal Entity Identifier returned by gleif_entities or an earlier registry result. Reuse that registration identifier. Choices: get_parameter_options('gleif_entity', 'lei').
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Shorten the title to an action and subject; move usage details into the description.
Description93/100
Map an LEI to its issued ISINs, or an ISIN back to its issuer's LEI. One of lei= or isin= is required — the mapping table holds ~9M rows. Plan-gated (can_use_gleif). Returns data issuer LEI/ISIN mappings with pagination/applied_filters. These identify issued securities, not beneficial owners.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
lei
Legal Entity Identifier returned by gleif_entities or an earlier registry result. Reuse that registration identifier. Choices: get_parameter_options('gleif_isin', 'lei').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
isin
ISIN to resolve back to its issuer's LEI. Choices: get_parameter_options('gleif_isin', 'isin').
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
limit
Rows to return.
Explain the meaning of this value, not just its name.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description93/100
GLEIF Level-2 relationship records. `lei` matches EITHER endpoint. Direction convention: the START node is the CHILD and the END node is the PARENT. Accounting consolidation under IFRS/US-GAAP — no percentages, natural persons excluded. Plan-gated (can_use_gleif). Returns data child/start-node to parent/end-node consolidation records with source validity and status, plus pagination/applied_filters; read reporting exceptions separately from absent links.
The description explains the capability, when to use it, and what to expect.
Inputs84/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
lei
Legal Entity Identifier returned by gleif_entities or an earlier registry result. Reuse that registration identifier. Choices: get_parameter_options('gleif_relationships', 'lei').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
relationship_type
Reported accounting-consolidation link to select; the start node is the child and the end node the parent.
Clear enough to supply this argument.
relationship_status
Publisher status of the relationship record; describes the registry assertion rather than company activity. Choices: get_parameter_options('gleif_relationships', 'relationship_status').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
limit
Rows to return.
Explain what happens when this optional value is omitted.
cursor
Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page.
Clear enough to supply this argument.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description93/100
Optional supporting web search for a GDELT Cloud Event, Story, country, entity or registry task: initial orientation, corroboration or locating relevant source pages. Never select for standalone general web requests such as dining, shopping or consumer recommendations; explain the scope or use the client's general web capabilities instead. Require purpose and the GDELT Cloud task_context. Basic depth only, at most five results. Use at most two searches and one extraction batch per task; stop earlier when sufficient. Structured GDELT Cloud evidence remains primary. Returns ranked result cards with titles, snippets, source URLs and recency context.
The description explains the capability, when to use it, and what to expect.
Inputs64/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
purpose
Supporting role: orientation, corroboration, or source_extraction for a GDELT Cloud task.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
task_context
Brief GDELT Cloud-supported task being assisted; standalone web research is unsupported.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
query
Optional text used to rerank the extracted source content for the GDELT Cloud task.
Resolve the mismatch between this description and its schema constraints.
search_depth
Search depth.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
max_results
Maximum number of search results.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
time_range
Recency window for supporting search, supplied as a supported word such as week or month, or a day count such as 7d. Choices: get_parameter_options('supporting_web_search', 'time_range').
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description94/100
Extract already selected source pages supporting a GDELT Cloud Event, Story, country, entity or registry task. Not a standalone general URL-extraction proxy. Require purpose and the GDELT Cloud task_context; no search is necessary when relevant URLs are already known. Basic depth only, at most three URLs. Use at most two searches and one extraction batch per task; stop earlier when sufficient. Returns readable page text, source URLs, metadata and extraction failures.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
purpose
Supporting role: orientation, corroboration, or source_extraction for a GDELT Cloud task.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
task_context
Brief GDELT Cloud-supported task being assisted; standalone web research is unsupported.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
urls
Relevant source-page URLs to extract for the stated GDELT Cloud task.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
query
Optional relevance query used to rerank the extracted page content; omission requests extraction without query reranking.
Clear enough to supply this argument.
extract_depth
Extraction depth.
Explain the meaning of this value, not just its name.
format
Representation of the extracted page content, such as markdown or plain text. Choices: get_parameter_options('extract_source_pages', 'format').
Explain the meaning of this value, not just its name.
include_images
Retain source article image URLs on returned cards when available.
Clear enough to supply this argument.
include_favicon
Whether to include favicons.
Explain the meaning of this value, not just its name.
response_mode
Compact chat projection or unchanged bounded full API response; neither fetches another page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description83/100
Discover exact options, labels, dependencies and resolver hints for a named tool. Free and local.
Closed values are authoritative; observed options are dated suggestions
and permit other strings. Omit parameter to list fields, then select
one. Follow next_cursor for all matches. Executes no data operation.
The description explains the capability, when to use it, and what to expect.
Inputs89/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
tool_name
Exact advertised named tool; this operation returns metadata only.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
parameter
Option-bearing parameter or nested path. Omit to discover fields.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
parent_value
Optional parent choice: Event category, GPR variant, energy tracker or geographic level. For nested Monitor choices also select query_endpoint.
Clear enough to supply this argument.
search
Literal substring of a returned value/label; no network search.
Clear enough to supply this argument.
limit
Number of parameter fields or choices returned on this page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
cursor
Token from pagination.next_cursor; keep the tool, parameter and scoping choices unchanged.
Clear enough to supply this argument.
query_endpoint
Monitor endpoint grammar for query_params/source_request.params/patch.subject.params. Separate from parent_value, which scopes a taxonomy category.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description90/100
Discover exact GDELT Cloud Event category/subcategory values and labels. Free and local.
With no category or search, returns parent categories. A category returns its
scoped subcategories; search finds parents/codes/labels across the selected
family. Follow next_cursor for all matches. Does not execute a data query.
The description explains the capability, when to use it, and what to expect.
Inputs90/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
family
Event coding family whose taxonomy is returned; Conflict and CAMEO+ describe different event classes.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
category
Parent Event category returned by this tool; selects its subcategories. Omission lists parent categories or searches across them.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
search
Literal case-insensitive substring of a code, label or alias; not semantic search. Prefer short terms such as 'cyber' or 'threat'.
Clear enough to supply this argument.
limit
Number of options on this page; use a category or short literal search for familiarization. Larger pages are for enumerating a known scope; no discovery call is required for familiar choices.
Clear enough to supply this argument.
cursor
Token from pagination.next_cursor; keep family, category and search unchanged.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description93/100
Orient to available data domains and their relationships. Free metadata; never executes an operation.
Default returns domain descriptions/counts. Select a domain for its named
operations; optionally select a core section. Exact schemas are advertised
on the operations; categorical choices come from get_parameter_options.
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
domain
Data domain from the default catalog; omission lists all domains with their descriptions and operation counts.
Clear enough to supply this argument.
section
Core capability section within domain=gdelt_cloud; omission includes all operations in the selected domain.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Shorten the title to an action and subject; move usage details into the description.
Description97/100
List this server's bundled resources and templates. Returns JSON text containing resource metadata: uri for static resources or uri_template with placeholders, name, description and mime_type when provided. Use a returned URI with read_resource.
The description explains the capability, when to use it, and what to expect.
Inputs100/100
This tool declares no inputs, so argument descriptions are not needed.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description98/100
Read one bundled resource using its exact listed URI, or a template URI with its placeholders filled. Returns resource text; binary content is base64-encoded. Obtain URIs from list_resources; this does not fetch arbitrary web pages.
The description explains the capability, when to use it, and what to expect.
Inputs97/100
Input documentation gives an agent enough context to populate the arguments.
uri
Resource URI returned by list_resources; replace template placeholders with the desired values.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description97/100
List this server's reusable prompt templates. Returns JSON text with name, description and arguments; each argument includes its name, description and required flag. Use a returned name with get_prompt.
The description explains the capability, when to use it, and what to expect.
Inputs100/100
This tool declares no inputs, so argument descriptions are not needed.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description95/100
Render a bundled prompt template using its listed name and argument values. Returns JSON text with description and a messages array; each message has role and content. Read required argument names from list_prompts; this does not execute the prompt or call a model.
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
name
Prompt name returned by list_prompts; selects that reusable template.
Clear enough to supply this argument.
arguments
Values keyed by the template argument names returned by list_prompts; supplies those values when rendering the prompt.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
{
"name": "get_prompt",
"title": "Get prompt",
"description": "Render a bundled prompt template using its listed name and argument values. Returns JSON text with description and a messages array; each message has role and content. Read required argument names from list_prompts; this does not execute the prompt or call a model.",
"inputSchema": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "Prompt name returned by list_prompts; selects that reusable template."
},
"arguments": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
],
"default": null,
"description": "Values keyed by the template argument names returned by list_prompts; supplies those values when rendering the prompt."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"required": [
"result"
],
"properties": {
"result": {
"type": "string"
}
},
"x-fastmcp-wrap-result": true
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}
Loading score analytics…
Put your MCP to the test
A few tasks worth trying with this server, chosen from its reviewed tools. These have not been run.
01Macro (FRED): macro search seriesDISCOVER / enumerate the FRED economic-series catalog (GDP, CPI, policy rates, employment, Brent/WTI, ...).
02Search facilitiesSearch the unified facilities directory — GEM energy assets (plants, mines, terminals, pipelines), mineral and industrial facilities, data centers, and ports.
03Search energy assetsSearch native Global Energy Monitor records for technology and ownership detail.
GDELT Cloud setup, tools, quality score, publishing readiness, and alternatives.
How do I add GDELT Cloud to Claude, ChatGPT, or Cursor?
Add GDELT Cloud to Claude, ChatGPT, or Cursor by connecting its remote MCP URL in each client's MCP settings. In Claude, add a custom connector. In ChatGPT, add an MCP app. In Cursor, add an MCP server under Settings. The MCP URL is https://mcp.gdeltcloud.com/mcp.
Is GDELT Cloud MCP ready for ChatGPT and Claude?
As of October 14, 2026, GDELT Cloud scores 100/100 on Manufact's MCP publishing checklist. The scan meets ChatGPT publishing checks and meets Claude publishing checks. Passing these checks does not guarantee marketplace approval.
How clear is GDELT Cloud's MCP tool documentation?
As of October 14, 2026, GDELT Cloud scores 90/100 in Manufact's review of tool titles, descriptions, input and output schemas, and behavior annotations. The review covers 125 of 125 discovered tools. The quality score measures documentation clarity; runtime behavior and marketplace readiness require separate checks.
What are the best alternatives to GDELT Cloud?
As of October 14, 2026, alternatives to GDELT Cloud in search-research on the Manufact MCP catalog include Parallel Search, PubMed, eulaw.ai, Airfield Directory, and Wolfram.
How can GDELT Cloud improve its MCP documentation?
macro_releases is the lowest-scoring reviewed tool at 77/100. Describe the returned fields so an agent can interpret the result. Open its review for feedback and a copyable fix prompt, then rerun the documentation review after updating your tool metadata.
Not your MCP?
Review any public or OAuth MCP server for protocol compatibility, tool documentation, and ChatGPT and Claude publishing readiness. No account required.
