The Taiwan Stock Agent server provides comprehensive real-time and historical data, technical analysis, and market insights for Taiwan stocks, managed via the Model Context Protocol.
Stock Information: Retrieve detailed company profiles, industry classifications, market sector, and valuation data for specific stocks
Price Data: Access both historical stock prices (OHLCV) for customizable periods and real-time current prices with trading volumes
Technical Analysis: Perform "Best Four Points" analysis to identify key buying and selling points with potential buy/sell signals
Market Overview: Monitor major market indices and general Taiwan stock market conditions
Resource Management: List available MCP resources with templates and examples, subscribe to updates for caching and notifications, and invalidate resource cache to ensure fresh data retrieval
Used for asynchronous HTTP client operations to fetch stock data from Taiwan Stock Exchange APIs
Provides HTTP transport layer for the MCP server as part of the dual architecture implementation
Serves as a database persistence layer option for storing historical stock data and caching
Handles data validation and structured output for stock information, price data, and market analysis
Provides testing framework for unit and integration tests of stock data services
Core runtime environment for the MCP server providing Taiwan stock market data and analysis tools
Provides caching layer for stock data with configurable TTL for real-time and historical information
Ensures code quality and formatting standards for the stock analysis service codebase
Provides ORM layer for database operations and stock data persistence
Serves as a lightweight database option for storing Taiwan stock exchange data and metadata
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Taiwan Stock Agent show me the real-time price and volume for TSMC (2330)"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
tw-stock-agent 是一個基於 Model Context Protocol (MCP) 的服務器，提供台灣股市資料查詢與分析功能。項目目前處於開發階段，正在進行架構重構以實現生產就緒的狀態。
台灣上市上櫃股票基本資料（公司概況、產業別、市值等）
股票歷史價格走勢和技術分析
即時股票資訊和市場概況
四大買賣點技術分析
Taiwan Stock Exchange (TWSE) 和 Taipei Exchange (TPEx) 數據
基於 FastMCP 框架的 MCP 協議實現
異步 I/O 處理和高效能快取
結構化輸出與 Pydantic 數據驗證
完整的錯誤處理和日誌記錄
支援多種 MCP 傳輸協議
Related MCP server: TWSE MCP Server
⚠️ 重要提示: 本專案目前正在進行架構重構，請參考 TODO.md 了解開發路線圖。
當前架構狀態:
✅ 基本 MCP 工具實現
🔄 正在整合雙架構（FastAPI + FastMCP）
🔄 實現完整異步 I/O 模式
⏳ 待實現結構化輸出和資源模式
⏳ 待添加資料庫持久化層
Python: 3.11 或更高版本
套件管理: 僅支援 uv（依照 CLAUDE.md 開發規範）
克隆專案：
git clone https://github.com/clsung/tw-stock-agent.git
cd tw-stock-agent安裝依賴（僅使用 uv）：
uv sync設置 pre-commit hooks：
uv run pre-commit install環境配置：
# 複製環境變數模板（如果存在）
cp .env.example .env# 使用 FastMCP 服務器（推薦）
uv run python mcp_server.py
# 使用 MCP 開發工具
uv run mcp dev mcp_server.py當前實現方式（FastMCP stdio 模式）：
{
"mcpServers": {
"tw-stock-agent": {
"command": "uv",
"args": ["run", "python", "mcp_server.py"],
"cwd": "/path/to/tw-stock-agent"
}
}
}未來支援（HTTP 傳輸）：
{
"mcpServers": {
"tw-stock-agent": {
"command": "uvicorn",
"args": ["tw_stock_agent.main:app", "--host", "127.0.0.1", "--port", "8000"]
}
}
}⚠️ 注意: HTTP 傳輸配置將在架構重構完成後可用。
工具名稱 | 參數 | 功能描述 |
|
| 獲取股票基本資料（公司概況、產業別、市值等） |
|
| 獲取歷史價格數據（OHLCV、成交量） |
|
| 獲取即時股票資訊（當前價格、成交量） |
|
| 四大買賣點技術分析 |
| 無 | 大盤指數和市場概況 |
stock://info/{stock_code} - 股票基本資訊
stock://price/{stock_code} - 價格歷史
stock://realtime/{stock_code} - 即時數據
TWSE (台灣證券交易所): 上市股票、TAIEX 指數
TPEx (證券櫃檯買賣中心): 上櫃股票、興櫃市場
使用 twstock 函式庫進行資料擷取
即時資料快取：1分鐘 TTL
歷史資料快取：30分鐘 TTL
API 速率限制：每5秒最多3個請求（符合 TWSE 限制）
tw-stock-agent/
├── CLAUDE.md # 開發規範與指導原則
├── TODO.md # 開發路線圖與改進計劃
├── README.md
├── pyproject.toml
├── mcp_server.py # 🔄 FastMCP 伺服器實現
├── tw_stock_agent/
│ ├── main.py # ⚠️ FastAPI 實現（將移除）
│ ├── services/
│ │ ├── stock_service.py # 股票資料服務
│ │ └── cache_service.py # 快取服務
│ ├── tools/
│ │ ├── stock_tools.py # MCP 工具定義
│ │ ├── stock_code.py # 股票代碼工具
│ │ └── *.csv # 股票交易所資料
│ └── utils/
│ ├── config.py # 配置管理
│ ├── data_fetcher.py # 資料擷取工具
│ ├── error_handler.py # 錯誤處理
│ └── rate_limiter.py # 速率限制
├── scripts/ # 獨立資料收集腳本
│ ├── download_twse.py # TWSE 資料下載
│ ├── download_tpex.py # TPEx 資料下載
│ └── ...
└── tests/
├── unit/
└── integration/目標架構 (參考 TODO.md):
🎯 整合為純 FastMCP 架構
🎯 完整異步 I/O 實現
🎯 結構化資料輸出
🎯 資料庫持久化層
🎯 全面錯誤處理和監控
技術棧:
MCP 框架: FastMCP (代替雙重架構)
資料驗證: Pydantic v2
HTTP 客戶端: aiohttp (異步)
資料庫: SQLAlchemy + SQLite/PostgreSQL
快取: Redis (生產) / 記憶體快取 (開發)
測試: pytest + anyio
詳細的開發規範請參考 CLAUDE.md。
# 安裝依賴
uv sync
# 執行程式碼品質檢查
uv run ruff check --fix # 程式碼檢查與格式化
uv run ruff format # 程式碼格式化
uv run mypy tw_stock_agent/ # 型別檢查
# 執行測試
uv run pytest --cov=tw_stock_agent
# 執行 MCP 伺服器
uv run python mcp_server.py套件管理: 僅使用 uv，禁止使用 pip
程式碼風格: 遵循 PEP 8，使用 ruff 進行檢查
型別標註: 所有函數必須有完整的型別標註
文檔字串: 使用 Google 風格，公開 API 必須有文檔
測試: 使用 pytest + anyio 進行異步測試
行長度: 最大 88 字元
TWSE API: 每5秒最多3個請求
資料更新頻率: 交易時間內每分鐘更新
快取策略: 即時資料1分鐘，歷史資料30分鐘
市場交易時間: 週一至週五 09:00-13:30 (台灣時間)
假日處理: 遵循台灣股市交易日曆
資料完整性: 部分歷史資料可能有缺漏
目前存在雙架構實現 (FastAPI + FastMCP)
混合同步/異步程式設計模式
參數命名不一致 (stock_code vs stock_id)
缺乏結構化輸出和完整錯誤處理
請參考 TODO.md 了解改進計劃。
# 通過 MCP 客戶端調用工具範例
import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
async def example_usage():
server_params = StdioServerParameters(
command="uv",
args=["run", "python", "mcp_server.py"],
cwd="/path/to/tw-stock-agent"
)
async with stdio_client(server_params) as (read, write):
async with ClientSession(read, write) as session:
await session.initialize()
# 獲取台積電 (2330) 股票資料
result = await session.call_tool("get_stock_data", {
"stock_code": "2330"
})
print(f"股票資料: {result.content}")
# 獲取歷史價格
result = await session.call_tool("get_price_history", {
"stock_code": "2330",
"period": "1mo"
})
print(f"歷史價格: {result.content}")2330: 台積電 (TSMC)
2317: 鴻海 (Foxconn)
2454: 聯發科 (MediaTek)
2891: 中信金 (CTBC Financial)
3008: 大立光 (Largan Precision)
本專案採用 MIT 授權條款 - 詳見 LICENSE 文件。
歡迎貢獻程式碼、回報問題或提出改進建議：
開發者: 本專案正在積極開發中，歡迎參與貢獻！
Get Best Four Points analysis for a specific stock.
| Name | Required | Description | Default |
|---|---|---|---|
| stock_code | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the action ('Get...analysis') without detailing traits like whether it's read-only, requires authentication, has rate limits, or what the analysis output entails (e.g., format, data types). This leaves significant gaps in understanding the tool's 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?
The description is a single, straightforward sentence that is front-loaded and wastes no words. However, it's overly concise to the point of under-specification, lacking necessary details for clarity and completeness.
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?
Given the complexity of an analysis tool with no annotations, 1 parameter at 0% coverage, and no output schema, the description is incomplete. It doesn't explain what 'Best Four Points' means, the analysis scope, return values, or behavioral traits, making it inadequate for effective tool use.
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?
The input schema has 1 parameter with 0% description coverage, and the description does not add any meaning beyond the schema. It mentions 'a specific stock' but doesn't explain the 'stock_code' parameter's format, valid values, or semantics, failing to compensate for the low schema coverage.
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 the tool 'Get Best Four Points analysis for a specific stock,' which provides a verb ('Get') and resource ('analysis'), but it's vague about what 'Best Four Points' entails—it could refer to technical indicators, price levels, or other metrics without clarification. It doesn't distinguish from siblings like get_stock_data or get_price_history, leaving ambiguity in purpose.
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?
No guidance is provided on when to use this tool versus alternatives such as get_stock_data or get_price_history. The description implies it's for analysis of a specific stock, but it doesn't specify contexts, prerequisites, or exclusions, offering minimal direction for selection among sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get market overview information.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. However, it offers no information about traits like read-only status, destructive potential, rate limits, authentication needs, or response format. This is inadequate for a tool with zero annotation coverage.
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 description is a single sentence, which is appropriately concise, but it is under-specified rather than efficiently informative. It fails to front-load critical details, making it less helpful despite its brevity.
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?
Given the lack of annotations and output schema, the description is incomplete. It does not explain what 'market overview' includes, how it differs from sibling tools, or what the return values are, leaving significant gaps for the agent to understand the tool's context and usage.
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?
The tool has 0 parameters, and the schema description coverage is 100%, so no parameter information is needed. The baseline for this scenario is 4, as the description does not need to compensate for any parameter gaps, though it also adds no value 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 'Get market overview information' restates the tool name 'get_market_overview' in a tautological manner without specifying what 'market overview' entails or distinguishing it from sibling tools like get_realtime_data or get_stock_data. It provides a vague purpose without concrete details about what resource or data is retrieved.
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?
No guidance is provided on when to use this tool versus alternatives such as get_realtime_data or get_stock_data. The description lacks any context, prerequisites, or exclusions, leaving the agent with no information to differentiate this tool from its siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get historical price data for a specific stock.
| Name | Required | Description | Default |
|---|---|---|---|
| stock_code | Yes | ||
| period | No | 1mo |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool retrieves historical data but lacks details on permissions, rate limits, data format, or potential side effects. This is a significant gap for a data retrieval tool, as it doesn't clarify if it's read-only, requires authentication, or has other constraints.
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 description is a single, clear sentence with no wasted words, making it easy to parse and front-loaded with the core purpose. It efficiently communicates the essential action without unnecessary elaboration.
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?
Given the complexity of a data retrieval tool with no annotations, no output schema, and low parameter coverage, the description is incomplete. It doesn't address return values, error handling, or behavioral traits, leaving the agent with insufficient information to use the tool effectively beyond a basic understanding.
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?
The description mentions 'specific stock' and 'historical price data', which loosely maps to the 'stock_code' and 'period' parameters. However, with 0% schema description coverage and two parameters, it doesn't explain what 'stock_code' format to use (e.g., ticker symbol), what 'period' values are valid (e.g., '1mo', '1y'), or how the data is returned. This fails to compensate for the lack of schema details.
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 clearly states the tool's purpose with a specific verb ('Get') and resource ('historical price data for a specific stock'), making it easy to understand what it does. However, it doesn't distinguish this tool from sibling tools like 'get_stock_data' or 'get_realtime_data', which might offer similar or overlapping functionality.
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 description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'get_stock_data' or 'get_realtime_data', nor does it specify prerequisites, exclusions, or contexts for usage, leaving the agent to infer based on tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get real-time data for a specific stock.
| Name | Required | Description | Default |
|---|---|---|---|
| stock_code | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions 'real-time data' but does not specify details like data freshness, rate limits, authentication needs, or error handling. This leaves significant gaps in understanding how the tool behaves beyond its basic action.
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 description is a single, efficient sentence that directly states the tool's function without unnecessary words. It is front-loaded and appropriately sized, making it easy to parse quickly.
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?
Given the tool's complexity (a data retrieval operation with no annotations or output schema), the description is incomplete. It lacks details on return values, error conditions, or behavioral traits, making it insufficient for an AI agent to fully understand how to use the tool effectively in context.
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?
The input schema has 0% description coverage, with only a parameter 'stock_code' documented structurally. The description adds minimal semantics by implying the parameter is for a stock, but it does not explain format (e.g., ticker symbol), constraints, or examples, failing to compensate for the low schema coverage.
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 clearly states the verb 'Get' and the resource 'real-time data for a specific stock,' making the purpose understandable. However, it does not distinguish this tool from siblings like 'get_stock_data' or 'get_price_history,' which might also retrieve stock-related information, leaving some ambiguity about uniqueness.
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 description provides no guidance on when to use this tool versus alternatives such as 'get_stock_data' or 'get_price_history.' It lacks context about prerequisites, exclusions, or specific scenarios, offering only a basic statement of function without usage instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a specific stock.
| Name | Required | Description | Default |
|---|---|---|---|
| stock_code | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('Get') but doesn't clarify if this is a read-only operation, requires authentication, has rate limits, or what the output format might be. For a tool with zero annotation coverage, this leaves significant gaps in understanding its 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?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's appropriately sized and front-loaded, making it easy to parse quickly, though it could benefit from more detail given the lack of other documentation.
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?
Given the complexity of financial data tools, no annotations, no output schema, and low schema coverage, the description is incomplete. It doesn't address what 'detailed information' includes, how results are returned, or any prerequisites, making it inadequate for an agent to use this tool effectively without additional context.
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?
The schema description coverage is 0%, and the description doesn't add any meaning beyond the input schema. It mentions 'a specific stock' but doesn't explain what 'stock_code' represents (e.g., ticker symbol, format examples like 'AAPL' or 'GOOGL'), leaving the parameter semantics unclear and undocumented.
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 clearly states the verb ('Get') and resource ('detailed information about a specific stock'), making the purpose understandable. However, it doesn't distinguish this tool from potential siblings like 'get_realtime_data' or 'get_price_history', which might also provide stock information with different scopes or formats.
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 description provides no guidance on when to use this tool versus alternatives like 'get_realtime_data' or 'get_price_history'. It lacks context about what makes this tool unique, such as whether it returns comprehensive data, real-time updates, or historical trends, leaving the agent to guess based on tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Invalidate resource cache for fresh data
| Name | Required | Description | Default |
|---|---|---|---|
| resource_pattern | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool invalidates cache 'for fresh data', implying a mutation that refreshes data, but doesn't specify what gets invalidated (e.g., all cache, specific resources), whether it's destructive, permission requirements, or rate limits. This leaves critical behavioral traits unclear for a mutation tool.
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 description is a single, efficient sentence with no wasted words. It's front-loaded with the core action ('Invalidate resource cache') and purpose ('for fresh data'), making it easy to parse quickly. Every part of the sentence contributes to understanding the tool's intent.
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?
Given the tool's complexity (a mutation operation with one parameter), lack of annotations, no output schema, and 0% schema coverage, the description is incomplete. It doesn't cover parameter usage, behavioral details like side effects, or what happens after invalidation. For a cache-invalidation tool, this leaves too many gaps for reliable agent use.
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?
The schema description coverage is 0%, with one parameter ('resource_pattern') undocumented in the schema. The description doesn't mention parameters at all, failing to compensate for the schema gap. It doesn't explain what 'resource_pattern' means, its format, or how it affects the invalidation, leaving the parameter's purpose ambiguous.
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 'Invalidate resource cache for fresh data' states the tool's purpose with a specific verb ('invalidate') and resource ('cache'), but it's somewhat vague about what exactly gets invalidated. It doesn't clearly distinguish this from sibling tools like 'list_resources' or 'subscribe_resource' which might also involve cache operations. The purpose is understandable but lacks precision about scope and boundaries.
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 description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., after data updates), exclusions, or how it relates to sibling tools like 'get_realtime_data' or 'list_resources'. Without any usage context, the agent must infer when this tool is appropriate, which could lead to misuse.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available MCP resources with templates and examples
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool lists resources but doesn't describe how it behaves—e.g., whether it's read-only, if it requires authentication, rate limits, pagination, or what the output format looks like. For a tool with zero annotation coverage, this leaves significant gaps in understanding its operational traits.
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 description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's front-loaded with the core action and resource, making it easy to scan and understand quickly. Every part of the sentence contributes value by specifying scope ('all available MCP resources') and additional details ('with templates and examples').
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?
Given the tool's simplicity (0 parameters, no output schema, no annotations), the description is adequate but has clear gaps. It explains what the tool does but lacks behavioral context and usage guidelines. For a basic listing tool, it meets the minimum viable standard but doesn't provide enough information for optimal agent use without additional inference.
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?
The input schema has 0 parameters with 100% coverage, so the schema fully documents that no inputs are required. The description adds no parameter information, which is appropriate here. Since there are no parameters, the baseline score is 4, as the description doesn't need to compensate for any gaps.
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 clearly states the verb ('List') and resource ('all available MCP resources'), specifying what the tool does. It adds detail about including 'templates and examples', which helps differentiate it from generic listing tools. However, it doesn't explicitly distinguish from sibling tools like 'get_stock_data' or 'get_market_overview', which appear to be more specific resource-fetching operations.
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 description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, context for usage, or comparisons to sibling tools like 'get_stock_data' or 'subscribe_resource'. Users must infer usage from the purpose alone, which is insufficient for effective tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Subscribe to resource updates for caching and notifications
| Name | Required | Description | Default |
|---|---|---|---|
| resource_uri | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It mentions 'caching and notifications' but lacks details on permissions, rate limits, side effects, or response format. This is inadequate for a subscription tool that likely involves ongoing processes or network operations.
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 description is a single, efficient sentence with no wasted words. It's front-loaded with the core action and purpose, making it easy to parse quickly.
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?
Given the complexity of a subscription tool (likely involving state changes or network calls), no annotations, no output schema, and poor parameter coverage, the description is incomplete. It doesn't address what happens after subscription, error conditions, or how it integrates with caching/notifications.
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 0%, so the description must compensate. It doesn't explain the 'resource_uri' parameter beyond what the schema provides (just a string). No details on format, examples, or how it relates to 'resource updates' are given, leaving the parameter's meaning unclear.
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 clearly states the action ('Subscribe') and purpose ('to resource updates for caching and notifications'), making the tool's function understandable. It doesn't differentiate from siblings like 'invalidate_cache' or 'list_resources', but it's not vague or tautological.
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?
No guidance is provided on when to use this tool versus alternatives like 'invalidate_cache' or 'list_resources'. The description implies usage for caching and notifications but doesn't specify contexts, prerequisites, or exclusions, leaving the agent to infer when it's appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The tools have some clear distinctions (e.g., market overview vs. stock-specific data), but there is notable overlap: get_stock_data, get_realtime_data, and get_price_history all target stock-specific information with ambiguous boundaries. get_best_four_points is distinct but could be confused as part of stock data. The descriptions help differentiate but don't fully resolve the ambiguity.
Most tools follow a consistent verb_noun pattern (e.g., get_market_overview, get_price_history, invalidate_cache), which is predictable and readable. However, list_resources and subscribe_resource deviate slightly by not starting with 'get', though they maintain the same snake_case style. This minor inconsistency keeps the naming mostly coherent.
With 8 tools, the count is well-scoped for a stock analysis server, falling within the typical 3-15 range. Each tool appears to serve a distinct purpose in the domain, such as data retrieval, caching, and subscriptions, without feeling excessive or insufficient for the stated functionality.
The tool set covers core data retrieval (e.g., real-time, historical, overview) and utility functions (caching, subscriptions), but there are notable gaps: no tools for actions like buying/selling stocks, setting alerts, or analyzing trends beyond the 'best four points'. This limits agent workflows, as the surface is data-focused without operational capabilities.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Taiwan Stock Exchange (TWSE) open data as MCP tools: stock quotes, ETF data, 140+ public datasets.
Financial data MCP for market, company, news, macro, and US Congress research.
Twelve Data MCP: real-time & historical market data (stocks, crypto, forex, etc).
China A-share market data for research, backtesting and AI agents via MCP.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/clsung/tw-stock-agent'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
