# futures_search_markets Resolve a futures-market topic to ranked markets in our curated catalog. | Field | Value | | --- | --- | | Category | Futures (`futures`) | | Exposure | public | | MCP tool | `futures_search_markets` | | Documentation | https://www.agentdatasets.com/docs/tools/futures_search_markets | ## Description Resolve a futures-market topic to ranked markets in our curated catalog. Covers 20 CFTC COT markets across two report families: 13 Traders in Financial Futures (TFF) markets (Treasury, SOFR, E-mini equity index, and major FX futures) and 7 Disaggregated markets across energy (WTI crude oil, Henry Hub natural gas), metals (gold, copper), and grains (corn, soybeans, wheat SRW). The result is the shared envelope: `data.query` echoes the search and `data.matches` is the ranked list (best first); `meta` holds `source` ("futures_catalog") and the freshest match `as_of`; `pagination` is null — this is a bounded relevance list, not a paged one, so refine the query rather than expecting to page. Each match carries `market` (the stable key — pass it to `futures_get_positioning`), the CFTC `cftc_contract_market_code`, `name`, `report_name` (as CFTC publishes it), `exchange`, `group`, `report_type` (`tff` or `disaggregated`), `trader_categories` (the five categories valid for that family, in canonical order), `report_variants` (the ingested universes: `futures_only` and/or `futures_and_options`), `coverage` (first/last report week we hold, or null if none ingested yet), a `score` in [0, 1], and a `match_reason` (`market_key`/`cftc_code`/`name`/`keyword`). An empty/whitespace query returns no matches (a normal, empty success — not an error). Example: `futures_search_markets(query="WTI crude oil futures")`. ## Parameters Input schema advertised to MCP clients and mirrored by the REST query string. | Parameter | In | Type | Required | Default | Constraints | Description | | --- | --- | --- | --- | --- | --- | --- | | query | input | `string` | yes | — | — | Free-form search over 20 curated CFTC futures markets across TFF and Disaggregated COT: a concept ('10-year treasury futures', 'S&P 500', 'WTI crude oil', 'natgas', 'gold', 'corn'), a market-key fragment ('ust_10y', 'sofr', 'wti_crude'), or a CFTC contract-market code ('043602'). Call this FIRST when you have a topic rather than an exact market key, then pass a match's `market` to futures_get_positioning. | | limit | input | `integer` | no | 10 | min 1, max 50 | Max ranked matches to return (1–50). | ## Provenance - `cftc` — U.S. Commodity Futures Trading Commission, Weekly Traders in Financial Futures and Disaggregated COT futures-only and futures-and-options-combined reports for 20 curated financial and commodity futures markets (U.S. Government work, public domain (us-gov-public-domain)). See https://www.agentdatasets.com/docs/attribution.md - `futures_catalog` — Curated internal catalog (CFTC COT markets), Discovery catalog for futures-market search: the curated CFTC contract-market whitelist (Treasury, SOFR, E-mini equity index, FX, energy, metals, and grain futures); each match identifies its TFF or Disaggregated report family and valid trader categories; positioning data carries the `cftc` source tag (Names only CFTC public-domain contract markets (see the `cftc` entry); the catalog identifier itself carries no separate license). See https://www.agentdatasets.com/docs/attribution.md Dataset registry: `futures_cot_positioning`.