Server Quality Checklist

Tool Scores

• twse_realtime_quoteA
  4.1/5.0
  Behavior3/5

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

  No annotations present, so description carries full burden. Discloses update frequency and data source (basic market station vs OpenAPI). Lacks details on rate limits, authentication, or error handling.

  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?

  Concise three-sentence description plus an Args block. Efficiently conveys purpose, usage, and parameters. Could be slightly more streamlined but minimal waste.

  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?

  For a simple tool with output schema, description covers purpose, usage, parameters, and update frequency. No need to detail return values. Adequately complete.

  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 coverage is 0%, but description adds meaning: codes are stock symbols with examples, market is exchange type with default. Compensates for missing schema descriptions.

  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?

  Description clearly states it retrieves real-time stock quotes with approx 5-second updates, contrasting with OpenAPI's previous-day data. It distinguishes from sibling tools (datasets, ETF snapshot) by focusing on real-time quotes.

  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 context for when to use (real-time vs historical), and guidance on market parameter (tse vs otc). Does not explicitly exclude alternatives or mention when not to use, but context suffices.

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

• twse_describe_datasetA
  4.4/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the full burden. It explains the tool returns field definitions and implies read-only behavior, but does not explicitly state that it is non-destructive or discuss auth/rate limits.

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

  Conciseness5/5

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

  The description is very concise with two clear sentences. The first sentence states the purpose, and the second explains the parameter usage. No extraneous information.

  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?

  With an output schema provided, the description does not need to explain return values. It covers the tool's role in the workflow (use before fetching data) and is complete for a simple schema-inspection tool.

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

  Parameters5/5

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

  The only parameter dataset_id is described with a source (來自 twse_search_datasets) and an example ('exchangeReport/STOCK_DAY_ALL'), adding significant value beyond the schema's type-only definition.

  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 it is for viewing complete field definitions of a dataset, with a specific verb ('查看') and resource ('資料集的完整欄位定義'). It distinguishes itself from siblings like twse_search_datasets (searching) and twse_get_dataset (presumably fetching data).

  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?

  The description explicitly says to use it before fetching data to confirm which fields to filter/project (取資料前用來確認要過濾／投影哪些欄位). It provides clear context but does not include when-not-to-use or explicit alternatives.

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

• twse_get_datasetA
  4.5/5.0
  Behavior3/5

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

  With no annotations, the description carries full burden. It discloses server-side filtering, a hard limit of 200 for limit parameter, and auto-detection of code column name. However, it omits error handling, permissions, rate limits, or idempotency, so it's adequate but not comprehensive.

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

  Conciseness5/5

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

  The description is concise and well-structured: a one-sentence purpose, a crucial usage warning, then a bullet list of args. Every sentence adds value with no redundancy.

  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?

  The description covers core usage, filtering, and pagination. Since an output schema exists, return format is not needed. It lacks error handling or prerequisites, but for a data retrieval tool with good parameter docs, it's nearly complete.

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

  Parameters5/5

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

  Schema description coverage is 0%, so the description fully compensates. It explains all 6 parameters with concrete examples (e.g., dataset_id like 'exchangeReport/STOCK_DAY_ALL', code like '0050', match as dict, fields as array), adding meaning beyond the schema's type-only definitions.

  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 '取得證交所資料集內容' (get TWSE dataset content) with support for server-side filtering, field projection, and pagination. It distinguishes from siblings like twse_search_datasets (search) and twse_describe_dataset (describe structure) by focusing on retrieving actual data rows.

  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?

  The second paragraph explicitly advises using code/match/fields to narrow scope and warns against unconditional full pulls ('不要無條件拉全部'). It provides examples for each parameter and implies when to use filtering, fulfilling the when-to-use and when-not-to-use criteria.

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

• twse_search_datasetsA
  4.5/5.0
  Behavior4/5

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

  No annotations provided, so description must fully disclose behavior. It explains the search behavior, parameter effects, and that it matches codes/descriptions/field names. No destructive or side effects mentioned, but as a read operation this is acceptable. It lacks rate limit or permission info, but not critical.

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

  Conciseness5/5

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

  Description is concise: two sentences plus parameter list. Front-loaded with purpose, each sentence is necessary. No fluff or redundancy.

  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?

  Given an output schema exists, return values need not be described. The description covers purpose, parameters, and usage context (TWSE OpenAPI). Could mention that results include dataset_id, but output schema handles that.

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

  Parameters5/5

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

  Schema description coverage is 0%, yet the description adds rich meaning: query with examples (ETF, 基金), tag with examples (證券交易, 公司治理), and limit with default 25. This fully compensates for missing schema descriptions and helps agents understand usage.

  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 tool searches TWSE OpenAPI datasets to find dataset_id before fetching data. It specifies matching against codes, descriptions, and field names. This distinguishes it from sibling tools (describe, get, realtime quote, snapshot) which serve different purposes.

  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?

  The description advises using this tool before fetching data and provides parameter usage details (e.g., empty query lists all, tag filters by category). It does not explicitly mention when not to use it or alternatives, but the context and sibling names imply search is for discovery.

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

• etf_snapshotA
  4.9/5.0
  Behavior5/5

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

  Discloses parallel query of three tables, partial failure behavior (marks null, records caveats), and that include_realtime may be empty after hours. No annotations provided, so description carries full burden, and it excels.

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

  Conciseness5/5

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

  Efficient structure: summary line, comparison, behavior note, then args. No wasted words, front-loaded key info.

  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 2 parameters, no annotations, and existing output schema, the description covers purpose, behavior, and parameters adequately. No missing critical context.

  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 coverage is 0%, but the description explains code as ETF symbol with examples and include_realtime as real-time quote inclusion with caveat. Adds significant value, though could specify code format further.

  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 it retrieves a complete snapshot of a single ETF, merging three TWSE tables. The verb '取得' (get) and resource 'ETF 完整概況' are specific, and it distinguishes from siblings by noting it's faster than separate calls to twse_get_dataset.

  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?

  Explicit guidance: use when needing a comprehensive ETF overview in one call, comparing favorably to twse_get_dataset. Also notes partial failure handling (null + caveats), making it resilient.

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