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('fundamental_income', tickers=['2330'], as_of='2023-06-30')

Input Schema

TableJSON Schema

Name	Required	Description	Default
`end`	No
`as_of`	No
`limit`	No
`start`	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
`message`	No
`coverage`	No
`freshness`	No
`provenance`	No
`not_investment_advice`	No

TDQS

A4.6/5.0

Behavior5/5

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

The annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior, and the description substantially enriches this by explaining point-in-time disclosure filtering, coverage.missing semantics, provenance attribution, query_id replayability, and freshness.stale semantics. It explicitly warns against estimating or interpolating missing values, which is exactly the kind of behavioral nuance 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?

The description is long, but its length is justified by the tool's complexity and the critical point-in-time/missing-data semantics. It is front-loaded with the main purpose and uses starred sections and bold text to structure caveats clearly. Every paragraph adds operational value and the example anchors everything.

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 the annotated read-only idempotent profile and the presence of an output schema, the description is more than complete: it tells the agent how to interpret results, how to quote query_id for traceability, and how to behave when values are absent. It covers all six parameters and the return contract, leaving no material gap for correct invocation.

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?

With 0% schema description coverage, the description carries the full burden of explaining parameters. It does this well: it covers dataset_id, tickers with an example, start/end date format, as_of semantics, and limit max. It could additionally clarify the schema default limit of 500 versus the described max of 5000, but overall it compensates strongly for the schema gap.

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 clearly states the action ('Query rows') and the resource (dataset), and immediately adds the key distinguishing concept: built-in point-in-time look-ahead protection. This separates it from sibling tools like list_datasets or describe_dataset even without reading their schemas.

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?

Provides explicit guidance on when to pass as_of (backtesting/agent-learning) and when to omit it (present-day lookups), while warning about the consequence of omission. It also gives strict instructions on how to handle coverage.missing values, which is critical operational guidance. It does not explicitly name alternative sibling tools, but its usage boundaries are clear enough.

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

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4/5.0

Disambiguation4/5

The tools are largely distinct: querying, searching, backtesting, risk reads, alerts, memory, and audit functions each have clear homes. A few adjacent pairs (risk_read vs risk_assess, company_health_check vs positioning_read) could be confused, but the descriptions draw explicit boundaries.

Naming Consistency3/5

There are strong consistent clusters like list_*, get_*, run_*, and memory_*, but the *_read suffix alternates with noun-first names like company_health_check, and bare-verb tools like ask, calendar, chart, and screen break the pattern. The naming is readable but not uniform.

Tool Count2/5

Forty tools is well past the 25+ threshold and makes the surface heavy for an agent to navigate, even though the breadth reflects a genuinely wide platform. Several clusters could plausibly be consolidated without losing capability.

Completeness4/5

The tool surface covers the main lifecycle well: discovery, point-in-time querying, filings search and full text, backtesting, research, risk assessment, alerts, memory, approvals, and provenance verification. Minor gaps exist—no strategy management tools, no memory deletion, no bulk export—but agents can work around them.

Resources

Need Help?