# Tool reference

## DMAPI (`https://dmapi.aitouyan.work/mcp`)

Use the 25 public read-only tools by family:

- Latest quotes: `broker_snapshot`, `xbandNcf_snapshot`, `twosides_snapshot`.
- Historical quote frames: `broker_frames`, `xbandNcf_frames`, `twosides_frames`.
- Window summaries: `broker_trend`, `xbandNcf_trend`, `twosides_trend`.
- K-lines: `latest_kline`, `kline_series`. Net prices are omitted unless `include_net_price=true`.
- Institutions and universe: `dmapi_latest_institution`, `dmapi_institution_rows`, `dmapi_institution_trend`, `dmapi_universe`.
- Cross-market: `dmapi_eastmoney_market_snapshot`, `dmapi_eastmoney_market_series`, `dmapi_market_risk_proxy`.
- Treasury futures: `dmapi_futures_basis_irr`, `dmapi_futures_calendar_spread`, `dmapi_futures_deliverable_basket`.
- Bond ledger: `listoff_query`, `listoff_get_bond`, `listoff_fields`, `listoff_status`.

Prefer the source-specific compact quote tools. Use exact `codes`, a narrow `tenor_min`/`tenor_max`, short `start`/`end` windows, and conservative limits. `start` and `end` accept the server's documented date/time format; do not broaden a failed query without inspecting the error.

## NewsSystem (`https://news.aitouyan.work/mcp`)

- `search_news_knowledge`: narrow semantic/keyword retrieval over news and official documents; default `limit=5` is usually enough.
- `whats_new`: exact minute/hour/day lookback by publication, ingestion, or revision time.
- `list_stat_datasets`: discover structured statistical datasets.
- `list_stat_series`: discover series and units within one dataset.
- `list_stat_dimensions`: discover a bounded sample of dimension values.
- `get_stat_time_series`: one tightly filtered bounded series.
- `get_stat_cross_section`: one exact `period_key`; never substitute an as-of date.
- `get_stat_multi_series`: up to 8 filtered series, at most 366 days and 250 points.
- `query_analysis_table`: deterministic catalog-metric analysis; use catalog keys, not natural language or SQL.
- `get_stat_release_chain`: official revisions for a period.
- `get_stat_observation_evidence`: source document, revision, and table evidence for one observation.
- `search_unified_context`: hybrid search across news, knowledge, and the statistics catalog.

Default to `response_format="compact"`. Keep discovery and data retrieval separate so identifiers are verified before use.

## Authentication failures

- HTTP 401: missing, invalid, disabled, expired, or revoked Key.
- HTTP 403: the Key lacks the required `dmapi:read` or `news:read` scope.
- HTTP 503 with `auth_unavailable`: server-side Key store is unavailable; do not retry aggressively.

Keys are issued only by the service administrator. There is no public registration or recovery flow.
