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), and the description adds genuinely new operational context: default 30 rows / hard cap 200, server-side filtering semantics, exact-match code with candidate fallback, and the caveat that most daily tables carry the previous trading day's after-close data rather than live prices. That data-freshness disclosure is not derivable from annotations or schema.

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 with the core action and the dataset.search prerequisite, and every sentence carries instruction value. It loses a point because the entire guidance set is duplicated verbatim across English and Chinese, which inflates length for a reader that only needs one language.

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 a 9-parameter nested schema, full schema coverage, rich annotations and an output schema, the definition supplies exactly the missing layer: freshness caveats, default/limit behavior, filtering strategy, and cross-tool routing. Nothing an agent needs to invoke it correctly is absent.

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, but the description adds real meaning: concrete filter examples (top-N by dividend yield, P/E below 10), the exact-match nature of code, and the warning that code_candidates are look-alikes (MXF vs MXFFX) rather than valid answers. It stops short of detailing every parameter, which is reasonable given the schema already does.

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 (fetch rows) and resource (TWSE OpenAPI / TAIFEX OAS dataset), and explicitly separates itself from the sibling dataset.search by telling the agent to resolve dataset_id there first. An agent can distinguish it from dataset.describe/search and the snapshot.* tools without opening a 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/when-not guidance: resolve dataset_id via dataset.search, don't guess because each metric is its own table; use where + sort_by for rankings/screens rather than paging; route gainers/losers/limit-up counts to snapshot.movers. Names the alternative tool where one exists, so routing is unambiguous.

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 cover readOnly/idempotent/openWorld, yet the description adds substantial context beyond them: the data source (TWSE OpenAPI), the refresh cadence (after each trading day, not live), parallel fan-out across three datasets, and partial-failure semantics (a failed section is null plus a caveat, never a whole-call failure). That is exactly the operational detail an agent needs to interpret results.

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 with the outcome first, then source/caveat behavior, then the realtime alternative — good ordering. The only cost is that the full content is duplicated in English and Chinese, roughly doubling the token footprint for the same 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?

With readOnly annotations, a fully covered schema, and an output schema that already defines the return shape, the description covers everything remaining: freshness limits, degraded-result behavior, and the escape hatch to quote.realtime. An agent can call this correctly and interpret nulls without guessing.

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 'code' and 'include_realtime' are already documented in the schema, including the default and the extra outbound call cost. The description reinforces the realtime trade-off but adds no format or syntax detail 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+scope: one TWSE-listed ETF in a single call, returning fund profile, prior-day price/volume, and regular-savings popularity. It explicitly distinguishes itself from the sibling quote.realtime by naming it as the tool to use for live prices, so the agent can route 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 a clear when-to-use (one-call overview of a listed ETF) and a clear when-not-to-use with the named alternative: '價量為前一交易日，不是盤中即時；要當下價格請用 quote.realtime.' The include_realtime flag is also framed as a conditional escalation.

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, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: data source (TAIFEX OAS), staleness ('not live', latest trading day), coverage of regular plus after-hours sessions, and the candidate-only response when a name is ambiguous. It does not discuss rate limits or failure modes for unknown codes.

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 with the resource and returned fields, then scope limits, then input handling, then alternatives – a sensible order. The main cost is full bilingual duplication, which roughly doubles the length for a single-language reader, though it serves a bilingual user base and no sentence is filler.

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 not be explained, yet the description still names the key fields. Combined with source, freshness, session coverage, ambiguity handling and sibling routing, an agent has everything needed to select and call this tool 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% so the baseline is 3, but the description goes beyond the schema by giving additional accepted codes ('TMF', 'CDF') not in the schema example, listing Chinese-name aliases, and specifying the semantic consequence of an ambiguous name (candidates only). That ambiguity behavior is real parameter semantics the schema does not encode.

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: one TAIFEX futures contract for the latest trading day, and enumerates the exact contents (OHLC, volume, settlement, open interest by contract month, sessions, near-month summary, institutional and large-trader positions). It explicitly bounds scope with 'futures only; not live', which cleanly separates it from snapshot.market, snapshot.stock and snapshot.etf.

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 routing for out-of-scope needs: '只含期貨；選擇權與整體期貨籌碼請用 dataset.search 或 snapshot.market'. It also defines the ambiguous-name path (return candidates, confirm with the user, re-query by code), which tells the agent how to behave on a failed lookup. It does not explicitly position itself against snapshot.stock/snapshot.etf beyond the word 'futures', so not a full 5.

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 cover readOnly/idempotent/openWorld/non-destructive, but the description goes well beyond them: limit-up and limit-down are derived from previous close and tick size because the data carries no flag, the universe excludes ETFs and warrants, OTC is out of scope, and the data is a previous-day snapshot rather than live. The only shortfall is that it doesn't state the response shape or pagination behavior.

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, routing guidance and caveats are front-loaded and each English sentence carries distinct information. The entire content is then repeated verbatim in Chinese, which roughly doubles length without adding new facts for a single-language reader, though it may aid multilingual routing.

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, yet the description still sketches the row fields (code, name, close, change, percentage change, volume). Combined with the stated coverage universe, the derived-limit methodology, the source (TWSE OpenAPI) and the non-live timing, 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 description coverage is 100% and the schema's own text for `limit` is richer than the description, including the important note that limit-up/limit-down counts are unaffected by the limit. The description adds nothing about the parameter, 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?

The first sentence states a precise verb+resource+scope: percentage-change rankings among TWSE-listed stocks for the previous trading day, plus limit-up/limit-down counts. It explicitly names the sibling it is not (dataset.get sorted by price change, which ranks by absolute points). An agent can distinguish it from snapshot.market, snapshot.stock and dataset.get 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?

It names the exact user intents that select this tool ("top gainers / top losers / which stocks hit the daily limit") and gives an explicit when-not with the alternative (don't use dataset.get's change sort; use quote.realtime for live prices). Both the exclusion and the correct substitute are stated, not implied.

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), and the description adds substantial context beyond them: data is previous-trading-day not live, archive cutoffs (2026-09-29 for prices, 2026-10-20 for P/E/margin with nulls earlier), per-ESG-topic extra external call cost, and graceful null+caveats behavior instead of total failure.

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 purpose and constraints are front-loaded, but the entire content is then repeated in full in Chinese, roughly doubling length for an agent reader with near-identical payload. The parallel second half adds a few unique details (default ESG topics) but mostly duplicates the English text.

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 7-parameter, read-only aggregation tool this is thorough: it explains the multi-dataset merge, freshness cadence (daily/monthly/quarterly), archive windows, per-section call costs, null/caveats handling, and sibling routing. An output schema exists, so return-value detail is correctly not restated.

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 meaning the schema doesn't carry: the default ESG topic set used when an agent merely says 'ESG', the note that comparison mode silently drops all include_* options, and that ~half of ESG topics only apply to certain industries (absent ≠ zero).

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 ('One TWSE-listed company in a single call') and enumerates exactly what the snapshot contains (price/volume, P/E, yield, P/B, revenue, dividends, attention/disposition status, market cap). Explicitly distinguishes itself from siblings (quote.realtime for live prices, snapshot.etf for ETFs), so an agent can route correctly 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 per-parameter when-to-use rules: pass codes instead of code for 2-5 company comparison, history_days for recent trends, include_financials/governance/margin/esg_topics for optional sections. Names alternatives for adjacent needs ('要當下價格請用 quote.realtime', 'ETF 請用 snapshot.etf', lookup for names) and states comparison-mode exclusions.

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