tw-market-data

Query a dataset (PIT-safe)

query_dataset

Read-onlyIdempotent

Query rows with built-in look-ahead protection.

★ POINT-IN-TIME: pass `as_of` (YYYY-MM-DD) for backtesting/agent-learning. For non-point-in-time-safe
datasets (fundamentals, monthly_revenue, dividend_policy…) rows are filtered by DISCLOSURE date <= as_of,
so the agent only sees what was public at that moment. Omit as_of only for present-day lookups (warned).

★ IF A VALUE IS IN `coverage.missing`, IT IS NOT AVAILABLE. Say it is not available. **Never
estimate it, interpolate it, infer it from a neighbouring period, or carry the last known value
forward.** `coverage.missing` lists exactly what was requested and not returned, with a reason
(e.g. "9999 在 as_of 當日未上市"). An empty `data` array alongside a populated `missing` list is a
complete and correct answer to "what do you have" — not an invitation to fill the gap.

★ EVERY VALUE IS ATTRIBUTABLE. `provenance` carries {source, source_role, ingested_at, revision,
provenance_uri}; `meta.query_id` names this exact question. Quote the query_id when reporting a
number — `replay_query(query_id)` returns the bytes that were served, so the claim can be checked
later. `freshness.is_stale` is computed server-side against the dataset's own cadence budget;
`null` means it could not be determined, which is NOT the same as fresh.

Args:
    dataset_id: see list_datasets. tickers: e.g. ['2330','2317']. start/end: 'YYYY-MM-DD' range.
    as_of: knowledge-time cutoff 'YYYY-MM-DD' (use for backtests). limit: <=5000.
Returns: {meta:{table,coverage,row_count,as_of_applied,point_in_time_safe,warnings,query_id},
          data:[...], provenance:{...}, coverage:{requested,returned,missing,reason},
          freshness:{status,latest_available,expected_lag,is_stale}}
Example: query_dataset('income_statement', tickers=['2330'], as_of='2023-06-30')

Input Schema

TableJSON Schema

Name	Required	Description	Default
`end`	No
`as_of`	No
`limit`	No
`start`	No
`cursor`	No
`tickers`	No
`dataset_id`	Yes

Output Schema

TableJSON Schema

Name	Required	Description	Default
`data`	No
`hint`	No
`meta`	No
`error`	No
`status`	No
`blocked`	No
`license`	No
`message`	No
`coverage`	No
`freshness`	No
`provenance`	No
`attribution`	No
`not_investment_advice`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedSep 27, 2026

addedOutput schema / properties / attribution

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "additionalProperties": true,
+        "type": "object"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Attribution"
+}

addedOutput schema / properties / license

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": true,
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "License"
+}

Changed1 schema field changedSep 19, 2026

addedOutput schema / $defs / Freshness / properties / expected_lag_unit

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Expected Lag Unit"
+}

Changed1 schema field changedSep 2, 2026

addedInput schema / properties / cursor

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Cursor"
+}

AddedAug 29, 2026
RemovedAug 28, 2026

Changed9 schema fields changedAug 19, 2026

addedOutput schema / $defs / Coverage

Added value: +{
+  "additionalProperties": true,
+  "description": "What was asked for and what came back.\n\n``missing`` is THE anti-hallucination field. An agent handed an empty list for a ticker it asked\nabout will reason about the absence; an agent handed ``missing:[\"9999\"]`` with a reason cannot.",
+  "properties": {
+    "from_": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "From"
+    },
+    "missing": {
+      "anyOf": [
+        {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Missing"
+    },
+    "reason": {
+      "anyOf": [
+        {},
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Reason"
+    },
+    "reason_by_item": {
+      "anyOf": [
+        {
+          "additionalProperties": {
+            "type": "string"
+          },
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Reason By Item"
+    },
+    "requested": {
+      "anyOf": [
+        {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Requested"
+    },
+    "returned": {
+      "anyOf": [
+        {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Returned"
+    },
+    "to": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "To"
+    }
+  },
+  "title": "Coverage",
+  "type": "object"
+}

addedOutput schema / $defs / Freshness

Added value: +{
+  "additionalProperties": true,
+  "description": "Server-computed, against the dataset's OWN cadence budget.\n\n``is_stale`` is null — never false — when it could not be determined: a missing measurement is\nnot evidence of freshness. A dataset with no calendar budget (a reference table, an event feed\nthat fires a few times a year) is ``AS_OF`` and is never stale.",
+  "properties": {
+    "age_days": {
+      "anyOf": [
+        {
+          "type": "integer"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Age Days"
+    },
+    "detail": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Detail"
+    },
+    "expected_lag": {
+      "anyOf": [
+        {
+          "type": "integer"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Expected Lag"
+    },
+    "is_stale": {
+      "anyOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Is Stale"
+    },
+    "latest_available": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Latest Available"
+    },
+    "status": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Status"
+    }
+  },
+  "title": "Freshness",
+  "type": "object"
+}

addedOutput schema / $defs / Provenance

Added value: +{
+  "additionalProperties": true,
+  "description": "Where one value came from. Fields are null when unknown rather than absent — an absent key\nreads as \"this API does not do provenance\", a null reads as \"we do not know this one\".",
+  "properties": {
+    "ingested_at": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Ingested At"
+    },
+    "provenance_uri": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Provenance Uri"
+    },
+    "revision": {
+      "anyOf": [
+        {},
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Revision"
+    },
+    "source": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Source"
+    },
+    "source_role": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Source Role"
+    }
+  },
+  "title": "Provenance",
+  "type": "object"
+}

addedOutput schema / $defs / QueryMeta / properties / envelope_version

Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Envelope Version"
+}

addedOutput schema / $defs / QueryMeta / properties / query_id

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Query Id"
+}

addedOutput schema / properties / coverage

Added value: +{
+  "anyOf": [
+    {
+      "$ref": "#/$defs/Coverage"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

addedOutput schema / properties / freshness

Added value: +{
+  "anyOf": [
+    {
+      "$ref": "#/$defs/Freshness"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

addedOutput schema / properties / not_investment_advice

Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Not Investment Advice"
+}

addedOutput schema / properties / provenance

Added value: +{
+  "anyOf": [
+    {
+      "$ref": "#/$defs/Provenance"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

First observedAug 1, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), yet the description adds substantial non-obvious behavior: point-in-time filtering by disclosure date on look-ahead-unsafe datasets, the coverage.missing contract, provenance/revision fields, query_id replayability, and the meaning of is_stale=null versus false. This is exactly the added context annotations cannot express.

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?

Front-loads the point-in-time rule and uses ★ markers for scanability, and the example is high value. Some of the coverage.missing guidance is prescriptive output-interpretation policy that runs long, so a small trim would tighten it without losing meaning.

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

Completeness4/5

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

Output schema exists, so the detailed Returns block is redundant but harmless, and the description fully explains the PIT and missing-data contracts an agent must honor. The uncovered gaps are cursor/pagination behavior and the absence of any guidance on how to page through the <=5000 limit.

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 description coverage is 0%, so the description must carry parameter meaning, and it does for dataset_id, tickers, start/end, as_of, and the limit ceiling (<=5000). However, the 'cursor' parameter is never mentioned, leaving pagination semantics undocumented in both schema and description.

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?

Opens with a specific verb+resource ('Query rows') plus the defining trait ('built-in look-ahead protection'), and points to list_datasets for dataset_id, which cleanly separates it from describe_dataset and list_datasets. An agent can identify this as the row-fetching tool without opening the schema.

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?

Explicitly states when to pass as_of (backtesting/agent-learning) versus when to omit it (present-day lookups, and notes they are warned), names the alternative for dataset discovery (list_datasets), and gives a concrete call example. No inferential work is left to the agent.

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

All tw-market-data 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.

Resources

Need Help?