Skip to main content
Glama
tw-stock-mcp

tw-stock-mcp

by jiawei-hong

Screen Taiwan stocks

screen_stocks
Read-onlyIdempotent

Filter TWSE and TPEx stocks by end-of-day price, change, volume, turnover, valuation (P/E, dividend yield, P/B), and monthly revenue growth using optional min/max bounds; sort and limit results.

Instructions

Filter all TWSE and TPEx stocks by end-of-day price, change, volume and turnover, and by valuation (P/E, dividend yield, P/B) and monthly revenue growth. Every filter is an optional min_/max_ bound, e.g. {"min_dividend_yield": 5, "max_pe_ratio": 15, "min_turnover": 100000000}. Rows missing a filtered metric are excluded. Defaults to common stocks only; results are sorted by sort_by (default turnover, descending). Price filters use the latest (or given) trading day; fundamental filters always use the latest published snapshot, so date cannot be combined with them.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "screen_stocks"
  }
}

Input Schema

NameRequiredDescriptionDefault
dateNoTrading date for price filters. Not allowed with fundamental filters.
limitNoRows to return. Default 20.
orderNoDefault "desc".
typesNoDefault ["stock"]. Add "etf" to include ETFs.
marketNoOmit for both markets.
sort_byNoDefault "turnover".
max_priceNoMaximum Closing price, TWD
min_priceNoMinimum Closing price, TWD
max_volumeNoMaximum Shares traded
min_volumeNoMinimum Shares traded
max_pb_ratioNoMaximum Price/book ratio
max_pe_ratioNoMaximum Price/earnings ratio on the latest four quarters of EPS (only companies with positive earnings have one)
max_turnoverNoMaximum Turnover, TWD
min_pb_ratioNoMinimum Price/book ratio
min_pe_ratioNoMinimum Price/earnings ratio on the latest four quarters of EPS (only companies with positive earnings have one)
min_turnoverNoMinimum Turnover, TWD
max_revenue_yoyNoMaximum Latest monthly revenue growth year over year, %
min_revenue_yoyNoMinimum Latest monthly revenue growth year over year, %
max_change_percentNoMaximum Daily change, %
max_dividend_yieldNoMaximum Dividend yield, %, on the latest annual dividend; above 20% is usually a one-off distribution (flagged in notes)
min_change_percentNoMinimum Daily change, %
min_dividend_yieldNoMinimum Dividend yield, %, on the latest annual dividend; above 20% is usually a one-off distribution (flagged in notes)

Output Schema

NameRequiredDescriptionDefault
dateYesTrading date of the price data
notesYes
filtersYesThe bounds that were applied
matchedYesRows that passed every filter (before limit)
resultsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.2

TDQS

A4.2/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds genuinely useful behavior beyond that — rows missing a filtered metric are excluded, default sorting is turnover descending, and fundamental filters always read the latest published snapshot — but it does not discuss limit/truncation behavior or what an empty result means beyond the exclusion rule.

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?

Dense and front-loaded: purpose first, then convention, then exclusion rule, then defaults and the date restriction. A few clauses restate schema defaults (sort_by default turnover, descending), which is mild redundancy but earns its place as a single-glance summary.

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?

For a 22-parameter screening tool with full schema coverage, annotations and an output schema, the description covers the decisions the agent must make: filter convention, exclusion of missing metrics, type defaults, sort default and the date/fundamental incompatibility. Nothing needed to call 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 the baseline is 3. The description still adds meaning by explaining the uniform min_/max_ bound convention and giving a concrete example object with units (dividend yield in %, turnover in TWD), which helps an agent compose a valid call across 22 parameters.

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 opens with a specific verb and resource plus scope: 'Filter all TWSE and TPEx stocks', then enumerates the exact filter families (price, change, volume, turnover, P/E, dividend yield, P/B, monthly revenue growth). An agent can distinguish this screening tool from siblings like get_market_movers or search_security without opening the schema.

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?

It states concrete usage conditions: defaults to common stocks only, price filters use the latest or given trading day, and `date` cannot be combined with fundamental filters — a real trap the agent would otherwise hit. It does not explicitly name an alternative sibling or say when-not to use this tool, which keeps it below a 5.

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