Skip to main content
Glama
tw-stock-mcp

tw-stock-mcp

by jiawei-hong

Search Taiwan securities

search_security
Read-onlyIdempotent

Find Taiwan-listed securities by code or name, converting a company name or partial code into a usable security code for other tools.

Instructions

Find Taiwan-listed securities (TWSE 上市 = "tse", TPEx 上櫃 = "otc") by code or name. Use this to turn a company name such as "台積電" or a partial code such as "233" into a security code before calling other tools. Matches code or Traditional Chinese name; exact matches rank first, then prefix, then substring, with stocks before ETFs. By default searches stock, etf, preferred, etn, other; warrants and convertible bonds (95% of all listings) are excluded unless requested via types.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "query": "<query>"
    },
    "name": "search_security"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMaximum results to return (default 10).
queryYesCode or name fragment, e.g. "2330", "台積", "元大".
typesNoSecurity types to include. Default: ["stock","etf","preferred","etn","other"]. Add "warrant" or "convertible_bond" to search those.
marketNoRestrict to one market. Omit to search both.

Output Schema

NameRequiredDescriptionDefault
queryYes
resultsYes
truncatedYesTrue when more matches exist than returned.
total_matchesYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.2

TDQS

A4.9/5.0
Behavior5/5

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

Annotations only declare readOnly/idempotent/openWorld; the description adds substantive behavior beyond them: match surfaces (code or Traditional Chinese name), result ranking (exact > prefix > substring, stocks before ETFs), and the non-obvious default that warrants and convertible bonds — 95% of listings — are excluded unless requested. These are facts an agent cannot recover from the schema.

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?

Three sentences, front-loaded with purpose, then the workflow trigger, then matching and default-scope behavior. Parenthetical market codes are compact and no sentence is filler.

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?

An output schema exists, so return shape need not be described; with four simple flat parameters the description covers purpose, invocation trigger, match semantics, ranking, and the default type scope. Nothing essential to calling it correctly is missing.

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 100%, so baseline is 3, but the description genuinely adds meaning: it maps 'tse'/'otc' to TWSE/TPEx, which the enum labels do not, and explains why the `types` default excludes warrants and convertible bonds. It does not elaborate on `limit`, but the schema already handles that.

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?

States a specific verb and resource ('Find Taiwan-listed securities') and immediately decodes the market identifiers (TWSE 上市 = "tse", TPEx 上櫃 = "otc"). It also distinguishes its role from siblings by framing it as the code-lookup step that precedes other tools.

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?

Gives an explicit when-to-use trigger — 'turn a company name such as 台積電 or a partial code such as 233 into a security code before calling other tools' — with concrete input examples. That routing guidance is exactly what keeps an agent from passing a name into a quote tool.

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