Twelvedata

Etfs

etfs

Read-onlyIdempotent

Twelve Data reference list of supported ETF symbols (64,000+ listings worldwide) with exchange and country metadata — paged, default 200 rows, count is the total matched. Filter by symbol (e.g. "SPY"), country or exchange. Use to discover or validate ETF tickers before querying price endpoints. A stock ticker (e.g. "AAPL") is not an ETF and returns an empty list with empty_reason: wrong_instrument_class — use the stocks tool for those.

Input Schema

TableJSON Schema

Name	Required	Description
`page`	No	Page of the reference list (default 1). `count` in the response is the TOTAL matched; `data` is this page.
`symbol`	No	Optional ETF ticker filter (e.g. "SPY", "QQQ", "VTI").
`country`	No	Optional country filter — full name or alpha code (e.g. "Japan", "Germany", "United States", "US").
`exchange`	No	Optional exchange filter (e.g. "NASDAQ", "NYSE", "Binance").
`mic_code`	No	Optional ISO 10383 market identifier code filter (e.g. "XNAS", "XLON").
`outputsize`	No	Rows per page (default 200, max 5000). The unfiltered ETF list is 64,000+ rows, so narrow with symbol / country / exchange rather than raising this.

Output Schema

TableJSON Schema

Name	Required	Description
`code`	No	Response code
`status`	No	Response status
`message`	No	Response message

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 schema fields changedSep 20, 2026

changedInput schema / examples

Previous value: -[
-  {}
-]New value: +[
+  {
+    "symbol": "SPY"
+  },
+  {
+    "country": "United States",
+    "outputsize": 20
+  }
+]

addedInput schema / properties / country

Added value: +{
+  "description": "Optional country filter — full name or alpha code (e.g. \"Japan\", \"Germany\", \"United States\", \"US\").",
+  "type": "string"
+}

addedInput schema / properties / exchange

Added value: +{
+  "description": "Optional exchange filter (e.g. \"NASDAQ\", \"NYSE\", \"Binance\").",
+  "type": "string"
+}

addedInput schema / properties / mic_code

Added value: +{
+  "description": "Optional ISO 10383 market identifier code filter (e.g. \"XNAS\", \"XLON\").",
+  "type": "string"
+}

addedInput schema / properties / outputsize

Added value: +{
+  "description": "Rows per page (default 200, max 5000). The unfiltered ETF list is 64,000+ rows, so narrow with symbol / country / exchange rather than raising this.",
+  "type": "number"
+}

addedInput schema / properties / page

Added value: +{
+  "description": "Page of the reference list (default 1). `count` in the response is the TOTAL matched; `data` is this page.",
+  "type": "number"
+}

changedInput schema / properties / symbol / description

Previous value: -"Optional ETF ticker filter (e.g. \"SPY\")."New value: +"Optional ETF ticker filter (e.g. \"SPY\", \"QQQ\", \"VTI\")."

Changed1 schema field changedJun 24, 2026

addedInput schema / properties / symbol

Added value: +{
+  "description": "Optional ETF ticker filter (e.g. \"SPY\").",
+  "type": "string"
+}

Changed1 schema field changedMay 24, 2026
- removedInput schema / additionalProperties
```
Removed value: -true
```

Changed2 schema fields changedMay 22, 2026

addedInput schema / examples
```
Added value: +[
+  {}
+]
```

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "code": {
+      "description": "Response code",
+      "type": "number"
+    },
+    "message": {
+      "description": "Response message",
+      "type": "string"
+    },
+    "status": {
+      "description": "Response status",
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

First observedMay 20, 2026

TDQS

A4.9/5.0

Behavior5/5

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

The description adds useful behavioral context beyond the annotations: pagination with default 200 rows, `count` semantics, and the `empty_reason: wrong_instrument_class` edge case. Since annotations already mark it read-only and non-destructive, this is a strong level of transparency without contradiction.

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

Conciseness5/5

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

The description is one well-structured paragraph. Every sentence adds value: scope, pagination, filters, use case, and disambiguation from the stocks tool, with no filler.

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?

Given six optional parameters, a rich input schema, and an output schema, the description is complete. It covers purpose, filtering strategy, pagination behavior, and a key edge case, so an agent can select and invoke it correctly without ambiguity.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by advising to narrow with symbol/country/exchange filters rather than increasing outputsize for the 64,000+ row list, adding practical parameter usage context.

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 states it is a 'reference list of supported ETF symbols' with exchange and country metadata, naming the exact resource and scope. It distinguishes itself from the stocks tool by explicitly stating that stock tickers are not ETFs and should use the stocks tool.

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

Usage Guidelines5/5

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

It explicitly says to use it 'to discover or validate ETF tickers before querying price endpoints.' It also tells the agent what happens with a stock ticker and directs to the stocks tool, providing clear when-to-use and when-not-to-use guidance.

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

All Twelvedata 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.