Taiwan Market Open Data (Unofficial)

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

Annotations already cover read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description adds useful context beyond annotations: it reads only the local catalog, has no upstream row counts or latest dates, and returns an error when the dataset_id does not exist.

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

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

The English part is front-loaded and efficient, covering purpose, related parameters, scope, and error behavior in a few sentences. The description is doubled in Chinese, which is appropriate for a bilingual tool but reduces conciseness relative to a single-language equivalent.

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

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

With one required parameter fully documented by the schema, an output schema present, and rich annotations, the description supplies the remaining context an agent needs: what is returned, how the returned field keys are used by dataset.get, that the catalog is local-only, and that missing IDs should be resolved via dataset.search.

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

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

Schema description coverage is 100%, so the schema already documents the single dataset_id parameter with its origin and an example. The description reinforces that fields are keyed by the identifiers returned here and refers back to dataset.search for valid IDs, but it does not add syntax or format details beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: it shows one dataset's definition, including id, source, summary, tags, and field keys with Chinese descriptions. It distinguishes itself from siblings by noting that dataset.get's parameters use these field keys and that dataset.search should be used first when an id is missing.

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

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

It clearly routes the agent: use dataset.search to find a dataset_id if it does not exist, and it distinguishes this metadata-only read from dataset.get by explaining that the returned field keys feed dataset.get's where, sort_by, fields, and match parameters. It also notes that it reads only the local catalog and has no row counts or dates, which implies when not to use it for data access, but it does not explicitly state to use dataset.get for data.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), yet the description adds genuinely new behavior: the 30-row default vs 200 hard cap, that upstream returns the entire table (possibly tens of thousands of rows) so filtering is server-side, that most daily tables hold the previous trading day's after-close data, that the response note states the period, and the licensing terms.

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

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

The English portion is front-loaded and tight, and the Chinese section is not pure duplication — it adds the upstream-returns-everything detail. However the bilingual restatement makes the block longer than strictly necessary for a reader of either language, so it is efficient but not maximally economical.

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

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

For a 9-parameter tool with nested objects, enums, and an output schema, the description supplies everything an agent needs: prerequisite step, filtering/sorting strategy, paging defaults and caps, and the data-freshness caveat. Return-value shape is rightly left to the output schema.

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

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

Schema description coverage is 100%, so the schema already documents every parameter in detail (exact-match code semantics, where operators, limit caps, sort_by behavior). The description only restates this at a higher level ('code is an exact match; match and where') without adding syntax or format meaning beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (fetch rows from a TWSE OpenAPI or TAIFEX OAS dataset) and distinguishes itself from siblings by naming dataset.search as the required prerequisite for obtaining dataset_id. An agent can tell what this does and how it relates to dataset.describe/dataset.search without opening any schema.

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

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

Gives explicit when-to-use guidance ('find the dataset_id with dataset.search first; do not guess it'), an explicit alternative path ('for rankings and screens use where and sort_by instead of paging through rows'), and a freshness caveat telling the agent not to treat results as live prices. Nothing is left to inference.

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

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

Annotations already declare readOnly, idempotent, non-open-world, non-destructive, so safety is covered. The description adds genuinely useful behavior beyond that: it reads a local catalog with no upstream call, matches against dataset codes, Chinese descriptions and column names, requires every space-separated keyword to match, and sorts by relevance. Only minor gaps (no note on result shape/pagination) remain.

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

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

Purpose and the 'no upstream call' fact are front-loaded well, but the description is roughly doubled by a Chinese block that largely restates the English text, and its scope examples bloat it further. Much of the length is translation redundancy rather than additive information.

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

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

The tool is a search with an output schema present, so return values need not be described. Goal, invocation trigger, matching rules, filtering conventions, and the safe read-only nature are all covered, leaving nothing an agent needs missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: it explains keyword matching rules (Chinese or English, space-separated, all must match), the taifex/ code-prefix convention, and a concrete tag value ('期貨與選擇權') for futures/options filtering that the schema only gestures at.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Search the catalog of TWSE OpenAPI and TAIFEX OAS datasets') and immediately frames the output purpose ('get the dataset_id to fetch'), which cleanly separates it from dataset.get and dataset.describe. An agent can tell exactly what this tool is for.

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

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

Gives a clear workflow trigger ('取資料前先用這個找 dataset_id' / search before fetching) plus a strong heuristic: search before concluding the exchange lacks a dataset, listing the surprisingly broad categories covered. It stops short of naming the sibling tools (dataset.get / dataset.describe) explicitly as the next/alternative step.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description goes well beyond them: matching semantics (English short names and fund names only, not full legal names), normalization rules (全半形, 台/臺), coverage limits (TWSE listed only, no OTC), and the data source. That is exactly the extra behavioral context 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.

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

Front-loads purpose, example, and the 'use first' rule before the caveats. The main cost is the fully bilingual duplication, where the Chinese text largely restates the English, making it longer than strictly necessary without adding new facts.

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

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

An output schema exists, so return values need no explanation, and the description covers the non-obvious risks: partial English matching, missing full company names, and the OTC blind spot. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema with examples and the limit bounds (1–50, default 10). The description adds matching behavior around `query` but nothing about `limit`. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (find the code of a TWSE-listed company or fund from name or code), gives a concrete example (台積電 → 2330), and scopes it tightly to listed securities including ETFs. It is immediately distinguishable from sibling tools like quote.realtime or snapshot.etf, which return prices rather than identifiers.

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

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

Explicitly says to use it first when the user supplies only a name, and warns against guessing codes, plus a fallback path when an English name fails. It does not name a sibling alternative for the reverse case (code → data), so routing guidance is strong but not fully exhaustive.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds non-annotation facts: the ~5-second refresh cadence, the MIS source, and that the source 'is not covered by the Open Government Data License', along with the per-quote trading date.

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

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

Content is front-loaded (what it returns, refresh cadence, scope) followed by the usage boundary and market mapping. The bilingual presentation duplicates parts of the English text in Chinese, which costs some efficiency, but every block still carries distinct information.

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

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

For a read-only quote tool with an output schema present, the description covers source, licensing, refresh cadence, item limits and market semantics. It omits auth requirements and error/empty-result behavior, which would round it out to a 5.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds semantic value beyond the schema by mapping the enum to real-world asset classes ('ETF 與上市股票用 market="tse"，上櫃用 "otc"') and restating the 50-item cap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Intraday quotes'), a precise scope ('up to 50 TWSE-listed (market="tse") or OTC (market="otc") codes'), and the real-time differentiator ('refreshed about every 5 seconds'). It does not name a sibling (e.g. quote.lookup) to contrast against, so sibling differentiation is left implicit.

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

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

The clause 'OpenAPI 只有前一交易日資料，要當下的價格得走基本市況報導站' gives a clear when-to-use condition (needing the current price) versus previous-day data, plus market selection guidance ('ETF 與上市股票用 market="tse"，上櫃用 "otc"'). It stops short of naming an alternative sibling tool or stating exclusions explicitly.

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

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

Annotations already declare readOnly, idempotent, open-world, non-destructive. Beyond those, the description adds genuinely useful traits: source is TWSE OpenAPI updated after each trading day (not live), three datasets are merged with parallel queries, and a section that cannot be fetched returns null plus a caveat rather than failing the whole call.

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

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

Front-loads the core content (what the snapshot contains) before source, freshness, and failure semantics. The bilingual duplication roughly doubles length without adding new facts, but the structure stays purposeful and scannable.

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

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

With an output schema present, return-value detail is not required, and annotations carry the safety profile. The description nonetheless covers freshness, source, and partial-failure behavior, leaving little an agent needs to know in order to call this correctly.

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

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

Schema description coverage is 100%, so both parameters (code, include_realtime) are already documented in the schema. The description notes that include_realtime costs an extra outbound call, but that detail is also in the schema's own description, so it adds little beyond the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific resource and scope: one TWSE-listed ETF with fund profile, prior-day price/volume, and regular-savings popularity. It is clear what the tool gathers, though differentiation from sibling snapshot.stock/snapshot.futures is only implicit via the 'ETF' framing, and explicit only for quote.realtime.

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

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

Gives clear context: this is a non-live, after-close snapshot, and for current prices it points to quote.realtime. It provides a positive routing rule but states no explicit when-not or exclusion conditions for this tool itself, keeping it just below full marks.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world, so the safety profile is covered. The description adds real behavioral context beyond them: data source (TAIFEX OAS), that it is not live, that it covers both regular and after-hours sessions, and crucially that an ambiguous name returns candidates rather than erroring or guessing — a non-obvious control-flow behavior an agent must handle.

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

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

Content is front-loaded with the core purpose first, then input forms, then scope exclusions. The one structural weakness is that the entire content is duplicated bilingually (Chinese mirror of the English), roughly doubling length without adding information for a single-language reader.

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

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

An output schema exists so return-value explanation is not required, yet the description still sketches the payload. For a single-parameter, read-only, disambiguation-prone snapshot tool, the description covers source, freshness, scope boundaries, ambiguity handling and alternatives to siblings — essentially complete, with only minor redundancy in the bilingual restatement.

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

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

Schema coverage is 100% and there is only one parameter, so the baseline is 3. The description goes beyond the schema by listing concrete accepted codes ('TX', 'MTX', 'TMF', 'CDF') and Chinese names ('台指期', '小台', '台積電期貨') and by defining the multi-match resolution behavior, which the schema does not express.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific verb/resource combination — one TAIFEX futures contract for the latest trading day — and enumerates the returned data (OHLC, change, volume, settlement, open interest by month, near-month summary, institutional/large-trader positions, final settlement). It explicitly excludes options and aggregate futures chips, routing those to dataset.search or snapshot.market, so it is distinguishable from siblings without opening any schema.

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

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

Clearly states the input forms accepted ('TX', 'MTX' codes or Chinese names) and the disambiguation workflow: an ambiguous name returns candidates only, and the agent should confirm with the user then re-query by code. It also points to dataset.search / snapshot.market for options and overall futures positioning. It lacks an explicit statement of when this tool is preferred over the closer sibling snapshot.market beyond the scope hint, but the routing guidance is solid.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, openWorld). The description adds genuinely useful behavioral context beyond them: data is not live, reflects the previous trading day, and is sourced from TWSE OpenAPI and TAIFEX OAS — freshness is a critical trait for a market snapshot and is not derivable from annotations.

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

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

Front-loaded and well organized, but the entire content is duplicated verbatim in Chinese and English, roughly doubling length without adding new information for a single reader. The scope-specific guidance is somewhat interleaved with the content inventory, making it longer than necessary.

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

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

With an output schema present, the description needn't explain return values, and annotations carry the safety profile. Combined with the inventory of returned data, freshness caveat, source attribution, and sibling routing, an agent has everything needed to select and call it correctly.

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

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

Schema coverage is 100% and the enum values are already documented in the schema, so baseline is 3. The description goes further by explaining what each scope actually contains (events lists ex-dividend dates, shareholder meetings, attention/disposition stocks) and that the trading calendar is included in every scope, which the schema does not convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific resource and scope: whole-market overview for the previous trading day, enumerating exactly what it returns (TAIEX, turnover, advancers/decliners, top 10 by volume, futures positioning) plus scope-dependent additions. An agent can distinguish it from snapshot.stock and snapshot.futures without opening any schema.

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

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

Explicit routing rules: use scope="stock" or "futures" when only one side is needed; use snapshot.stock for a single stock's ex-dividend/attention/disposition status; use snapshot.futures for individual futures contract prices and positions. Both the when and the when-not (不含個別契約行情價格) are stated with named alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false. The description adds genuinely useful non-annotation detail: data source (TWSE OpenAPI), freshness semantics (daily tables are previous-trading-day, revenue monthly, financials quarterly, not live), per-section external-call cost, and graceful degradation ('any missing section is null and recorded in caveats, never fails entirely'). However partial coverage of the safety/latency profile keeps it from the top band.

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

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

The English text is front-loaded and each sentence in it earns its place, but the description is roughly doubled in length by a full Chinese restatement of the same content, which is redundant for most agents. The overall payload is long relative to the schema, which already carries the parameter detail.

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

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

With an output schema and full annotation coverage already present, the description still supplies everything an agent needs to call correctly: data freshness caveats, per-section external-call cost, comparison-vs-single mode semantics, and the null/caveats failure contract. Nothing material is missing.

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

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

Schema description coverage is 100%, so the baseline is 3; the schema already documents code, codes, history_days and each include_* flag. The description still adds meaning beyond the schema, notably the default ESG topic set when a user just says 'ESG' and the comparison-mode restriction. That marginal added guidance lifts it above baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource: 'One TWSE-listed company in a single call' and enumerates exactly what it returns (profile, prior-day price/volume, P/E, dividend yield, P/B, monthly revenue, dividends, ex-dividend dates, attention/disposition status, market cap). It also distinguishes itself from siblings by naming snapshot.etf for ETFs and quote.realtime for live prices. An agent can identify this tool without opening any schema.

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

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

Explicit when-to-use routing for each mode: pass codes instead of code for 2–5 company comparison, pass history_days for recent trend, and use quote.realtime for live prices. It names the sibling alternative for the ETF case. Exclusions are stated (comparison mode does not support the optional include_* sections).

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