Skip to main content

​
The server does not expose one tool per endpoint

There are 104 tools. Advertising them all would spend a large part of a model’s context describing an API before it has been asked anything, and the value lists alone run past a thousand entries. So each category exposes three thin tools instead — 45 in total — and the model walks down only the branch it needs: {category} is the category name from the table below — so the events tools are reached with gdelt_cloud_tool_list, gdelt_cloud_tool_get and gdelt_cloud_tool_call, and the maritime ones with maritime_tool_list and so on. Every dispatcher call keeps the nested tool inputs inside tool_arguments:
The trio is per category, not global. There is no single tool_list. Picking the category is the first decision, which is why each one below says when to reach for it.
The practical consequence for a model: fetch the schema with _tool_get before the first call to a tool it has not used in this conversation. Guessing a parameter name is the single most common failure, and the server rejects unknown filters rather than ignoring them.

​
Categories

​
GDELT Cloud

gdelt_cloud · Core Real-world dynamics — what happened, who did it, where, how often. Coded events, clustered stories, Situations, country context, publication activity and Monitors. For any named person, organization, place or facility, resolve first with unified_entity_search (country_match=strict), inspect the candidates, then call the destination tool with the selected id. Parameters and value lists are the endpoint’s own: see Events · Stories · Situations · Entities · Unified Search · Geography · Monitors · Atlas Intelligence in the API reference, or fetch them at call time with gdelt_cloud_tool_get.

​
Media Intelligence

media_intel · Core How an entity is covered by the press — tone over time and share of voice against a peer set. Parameters and value lists are the endpoint’s own: see Media Intelligence in the API reference, or fetch them at call time with media_intel_tool_get.

​
Facilities

facilities · Core The unified physical-asset directory — power plants, industrial sites, ports and data centers on one keyed surface, resolved to spine owners. Parameters and value lists are the endpoint’s own: see Facilities in the API reference, or fetch them at call time with facilities_tool_get.

​
Government

gov · Open Feeds US federal awards and foreign-influence registrations, resolved onto the entity spine. Parameters and value lists are the endpoint’s own: see Government in the API reference, or fetch them at call time with gov_tool_get.

​
Political Offices

offices · Open Feeds Public political offices and who held them, with the office start/end dates the publisher states (valid time), resolved onto the entity spine. Actor context for geopolitical analysis, not a PEP or sanctions screen. Reach the holders of an office through office= on the gdelt_cloud event and story tools. Parameters and value lists are the endpoint’s own: see Political Offices in the API reference, or fetch them at call time with offices_tool_get.

​
Filings

filings · Open Feeds SEC EDGAR — the filing index, XBRL financials, and relations extracted from filing text. Parameters and value lists are the endpoint’s own: see Filings in the API reference, or fetch them at call time with filings_tool_get.

​
Legal Entities

gleif · Open Feeds The GLEIF Global LEI Index — legal-entity reference data, consolidation relationships and LEI↔ISIN mappings. Parameters and value lists are the endpoint’s own: see Reference Data in the API reference, or fetch them at call time with gleif_tool_get.

​
Energy

energy · Open Feeds Global Energy Monitor assets and the ownership registry over them. Parameters and value lists are the endpoint’s own: see Energy in the API reference, or fetch them at call time with energy_tool_get.

​
AI Compute

epoch · Open Feeds Epoch AI — models, hardware, data centers, companies and chip sales. Parameters and value lists are the endpoint’s own: see AI Compute in the API reference, or fetch them at call time with epoch_tool_get.

​
Macro Finance

macro · Open Feeds FRED economic series, with true point-in-time vintages rather than the latest revision. Parameters and value lists are the endpoint’s own: see Macro Finance in the API reference, or fetch them at call time with macro_tool_get.

​
Risk and Screening

risk · Open Feeds Restricted-party lists, name screening, ownership-chain exposure and China development finance. Analytical coverage, not an audit-grade compliance control. Parameters and value lists are the endpoint’s own: see Screening and Reference · China in the API reference, or fetch them at call time with risk_tool_get.

​
Maritime

maritime · Open Feeds AIS-derived vessel flow — chokepoint transits, port dwell, dark gaps and last-known offices. Terrestrial AIS only, so coverage thins in open ocean. Parameters and value lists are the endpoint’s own: see Maritime in the API reference, or fetch them at call time with maritime_tool_get.

​
Prediction Markets

prediction_market · Vendor Kalshi contracts, read as a market-implied probability rather than a fact. A vendor surface reached through the same protocol — not GDELT Cloud data.

​
Web Research

web_research · Vendor Live web search and page extraction, for corroborating a finding against primary sources after the structured surfaces have answered. A vendor surface, not GDELT Cloud data.

​
Macro Finance (vendor)

macro_finance · Vendor Alpha Vantage market and economic series. Distinct from the macro category above, which is our FRED surface with point-in-time vintages — this one is a vendor passthrough. The catalog for this category is fetched from the provider at call time, so there is no fixed list to publish — ask macro_finance_tool_list for the current one. Reached through the same protocol, but not GDELT Cloud data — see External tools.

​
Monitor workflow

Monitors live in the gdelt_cloud category. Fetch each nested schema before its first use, then call the progressive dispatcher with the nested parameters in tool_arguments:
gdelt_cloud_tool_call is READ-ONLY and cannot change anything. Everything that creates, updates, pauses, deletes, persists a run, or sends delivery runs through a separate dispatcher, gdelt_cloud_tool_write, which reaches exactly eight tools: create_monitor, update_monitor, delete_monitor, set_monitor_enabled, configure_monitor_delivery, test_monitor_delivery, batch_monitors, run_monitor_now.
If you are writing a host approval policy, gate gdelt_cloud_tool_write. Gating gdelt_cloud_tool_call stops no mutation — the server refuses write tools there by name — while leaving gdelt_cloud_tool_write ungated permits every state change the integration can make.
Follow the same canonical contract as REST:
  1. Resolve an entity name with unified_entity_search, and present ambiguous candidates instead of guessing.
  2. Call preview_monitor; an accepted Preview costs 1 QU, saves nothing, and sends no delivery.
  3. Read the representative rows. Entity coverage is mention/link evidence, not material involvement or actor attribution.
  4. Call create_monitor only after the subject and rows are acceptable. Scheduled checks cost 0 QU.
  5. Use update_monitor for any canonical partial update, set_monitor_enabled for pause/resume, or batch_monitors to enable, disable, or permanently delete up to 100 ids.
  6. Use configure_monitor_delivery to set/remove a webhook or rotate its secret, and test_monitor_delivery to send a test event. The signing secret appears only on initial webhook configuration or explicit rotation; save it then because later reads never return it.
  7. Use run_monitor_now to persist an immediate test run for 1 QU without sending delivery, advancing match state, or changing the schedule. Inspect retained runs with list_monitor_runs, get_monitor_run, and get_monitor_run_matches.
For exact replay, take every returned replay_request, choose search_events or search_stories from its endpoint, and pass its day-bounded REST parameters through that nested tool’s discovered schema. Follow pagination.next_cursor to exhaustion, then retain only rows whose exact_window_filter.field timestamp is greater than or equal to start_inclusive and strictly less than end_exclusive. The day-bounded request alone is deliberately wider than the exact half-open scheduler window. Preserve every returned entity, taxonomy, geography, semantic, and deduplication parameter; union multi-entity requests and deduplicate canonical ids. preview_monitor and create_monitor compile the same public Monitor body. sample_count and run result_count are execution counts, while the returned rows are bounded samples. When count_truncated / total_matches_is_lower_bound is true, the semantic count reached the reported candidate_limit and is a lower bound rather than an exhaustive corpus total. Multi-entity replay returns one request per entity and endpoint; union and deduplicate canonical ids. See Monitors and Monitor webhooks.

​
What is metered

A _tool_call costs the same as the REST call it makes, against the same plan limits, and appears in the same usage reporting. _tool_list and _tool_get are discovery and are not metered. An endpoint your entitlement does not include returns an error naming what it needs — never an empty result, which would be indistinguishable from missing data. Scheduled Monitor checks are the exception to ordinary endpoint metering: they cost 0 QU; each accepted preview_monitor execution costs 1 QU.