World Monitor

Oil production and export series by country

get_oil_trade_series

Read-onlyIdempotent

Monthly oil supply and export series for 24 major exporters over 24 complete months, comparing the last N complete months with the N before and a year earlier (default N=6), e.g. UAE oil exports, last 6 months vs the 6 before. Four sources, never blended: production (EIA STEO liquids supply, revisable estimates); jodi (the country's own JODI crude and product exports; the UAE has filed none since 2019); mirror (Comtrade imports declared by buyers, a lagging sample compared only on buyers in basis.reporters); ais (PortWatch tanker loadings, an index that undercounts, not an export total). Uncovered months are null, never zero; each source has status and lastObserved. Weekly seed, stale after 14 days. Seeded-cache read: weight 1 on API plans, included in the signed-in free allowance. country adds monthly rows; window_months sets N (1-12).

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "get_oil_trade_series"
  }
}

Input Schema

Name	Required	Description
`country`	No	Countries as ISO alpha-2, alpha-3 or English names (e.g. ["AE"], ["Saudi Arabia"]). Selected countries include their monthly rows. Omit for every covered country, comparison only. Unresolved inputs return Invalid params; a resolvable country outside the 24 covered returns no row.
`summary`	No	Return counts + 3-item samples instead of full lists. Useful when you only need shape/size or want to budget context before drilling in.
`jmespath`	No	Optional JMESPath projection applied to the response. See initialize.instructions for grammar and examples.
`window_months`	No	Months per comparison window, ending at the last complete month (default 6: the last 6 complete months vs the 6 before, plus the same 6 months a year earlier).

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

AddedOct 19, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Annotations only cover the read-only/idempotent safety profile, and the description adds substantial behavioral context they cannot: revisable EIA estimates, the UAE's JODI gap since 2019, the mirror source being a lagging buyer-declared sample constrained to basis.reporters, and the AIS source being an undercounting index rather than an export total. It also discloses null-vs-zero semantics, per-source status/lastObserved, and a 14-day staleness window on the weekly seed — exactly the operational caveats an agent needs.

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

Conciseness4/5

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

Scope and the worked example are front-loaded, and essentially every sentence carries distinct information (sources, gap indicators, cache economics). It is dense and semicolon-heavy, which costs a little readability, but there is no filler or redundancy worth cutting.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-value shape need not be explained, yet the description still discloses the semantics that matter most (null never zero, status/lastObserved, four non-blended sources). Combined with the parameter notes and cache behavior, nothing an agent needs to call this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all four parameters in detail (including ISO format handling and unresolved-input behavior). The description's 'country adds monthly rows; window_months sets N (1-12)' only restates what the schema provides, adding no syntax or format meaning beyond it. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific resource and scope — 'Monthly oil supply and export series for 24 major exporters over 24 complete months' — and immediately concretizes it with a worked example. The four named sources (EIA STEO production, JODI, Comtrade mirror, PortWatch AIS) let an agent distinguish this from adjacent siblings like get_energy_intelligence or get_wto_trade_flows without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The example ('UAE oil exports, last 6 months vs the 6 before') plus the comparison logic and default N clearly signal the intended use case, and the pricing note ('weight 1 on API plans, included in the signed-in free allowance') flags cost. However, it never states when to prefer this over sibling energy/trade tools or what would push an agent elsewhere, so there are no explicit exclusions or alternatives.

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

All World Monitor tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.