Skip to main content
Glama
tw-stock-mcp

tw-stock-mcp

by jiawei-hong

Get top gainers, losers and most traded

get_market_movers
Read-onlyIdempotent

Retrieves end-of-day Taiwan stock and ETF rankings across TWSE and TPEx for top gainers, losers, volume, or turnover, with filters for date, market, security type, and minimum turnover.

Instructions

End-of-day ranking of Taiwan stocks and ETFs across TWSE and TPEx: top gainers, losers, or most traded by volume (shares) or turnover (TWD). Defaults to common stocks and ETFs; illiquid names can dominate gainer/loser lists, so set min_turnover (TWD) such as 100000000 to focus on actively traded names. Without date, uses the most recent trading day with published data (published around 14:30-15:00 Taipei). For intraday prices use get_quote.

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": "get_market_movers"
  }
}

Input Schema

NameRequiredDescriptionDefault
dateNoTrading date YYYY-MM-DD. Default: latest available.
limitNoRows to return. Default 10.
typesNoSecurity types to include. Default ["stock", "etf"].
marketNoOmit for both markets.
sort_byNoDefault "gainers".
min_turnoverNoExclude rows with turnover below this many TWD.

Output Schema

NameRequiredDescriptionDefault
dateYes
notesYes
moversYes
sort_byYes
consideredYesSecurities that passed the filters

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.2

TDQS

A4.7/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so safety is covered. The description adds real behavioral context beyond them — data freshness (published around 14:30–15:00 Taipei), the fallback to the most recent trading day with published data, and the data-quality caveat that illiquid names can skew gainer/loser lists. It does not discuss rate limits or row-cap interactions, keeping it short of a 5.

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, each earning its place: scope first, then the data-quality tuning tip, then the default-date behavior, then the alternative tool. No filler and no repetition of schema content.

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 six-parameter, zero-required ranking tool with a full output schema, the description covers what an agent needs: what the ranking means, market coverage, the liquidity pitfall and its fix, data freshness, and where to go for a different need. Return values are correctly left to the output schema.

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 description coverage is 100%, so the baseline is 3; the description earns above baseline by giving the min_turnover parameter concrete meaning (TWD threshold, e.g. 100000000 for actively traded names) and by explaining the date fallback semantics with publication timing. The types and sort_by enums are left entirely to the schema.

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: an end-of-day ranking of Taiwan stocks and ETFs across TWSE and TPEx, covering gainers, losers, and most-traded by volume (shares) or turnover (TWD). It is clearly distinguishable from siblings like get_quote and get_history because it names the exact scope (EOD ranking) rather than a per-security lookup.

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?

Explicitly frames this as end-of-day data and routes the agent elsewhere for intraday prices: 'For intraday prices use get_quote.' It also gives a concrete usage tactic (set min_turnover to ~100000000 to avoid illiquid names dominating the lists) and states the default behavior when no date is supplied.

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