This server is an MCP-based drink ordering system for the beverage shop "一沐日". It provides the following capabilities:
View Menu: Retrieve the full drink menu with prices and available toppings.
Place Orders: Submit new drink orders with customer name, drink name, sweetness/ice level specification, and optional toppings. Uses fuzzy matching to map natural language to menu items.
List Recent Orders: View the most recent orders with details.
Find Duplicate Orders by Name: Search for duplicate orders placed by a specific person.
Search All Duplicates: Identify all customers who have duplicate orders.
Get Duplicate Statistics: Get statistical insights into duplicate orders.
Update Orders: Modify existing orders by unique ID or by customer name, changing any combination of fields.
Delete Orders: Remove orders by unique ID or by customer name.
Provides tools for managing drink orders stored in Firebase Firestore, including placing, listing, updating, deleting, and finding duplicate orders.
Integrates with Google Cloud Firestore to enable CRUD operations for drink orders, duplicate detection, and order statistics.
Click on "Deploy 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., "@mcp-drink-main 幫林進源訂一杯粉粿桂花檸檬 無糖去冰"
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.
本專案是一個整合 Streamlit 網頁介面、Google Cloud Firestore (Firebase) 與 Model Context Protocol (MCP) 的智能點餐助理系統。透過本系統，使用者不僅可以使用傳統的網頁 UI 進行點餐與訂單管理，更能直接與 AI 點餐助手進行對話，由 AI 自動解析口語需求並呼叫 MCP 工具完成點餐、修改、刪除或進行重複訂單的篩選與統計。
專案由多個功能模組相互協作而成，主要元件如下：
角色：系統的前端視覺化操作介面。
功能：
提供直覺的點餐表單（選擇人名、飲品、甜度冰量、加料）。
即時從雲端 Firestore 載入訂單列表，並支援在網頁上直接「修改」或「刪除」訂單。
多 AI 廠商與雙模式切換側邊欄：
支援雲端模型（如 Gemini, OpenAI, Claude）與本地 Ollama 模型（如 Gemma 4, Qwen 等）雙模式。
雲端模式下會自動顯示目前採用的 API 與模型版本。
本地模式下會自動偵測本地已下載的 Ollama 模型清單並提供下拉選單切換，並優先建議 gemma4。
無論雲端或本地，皆可透過 OpenAI 相容協定或 Native SDK 發送對話並在背景安全解析 MCP 工具。
角色：基於 Model Context Protocol (MCP) 標準的後端服務。
功能：
註冊並暴露多個點餐工具（Tools）給支援 MCP 的大語言模型（如 Claude Desktop 或內置的 Streamlit AI 助手）。
支援工具清單：
get_menu：查詢目前的完整飲品菜單與加料選項。
place_drink_order：為特定人名點購飲品（會自動驗證甜度冰量與計算金額）。
list_recent_orders：列出最近的 10 筆訂單。
find_duplicate_orders_by_name：查詢特定人名的重複訂單。
search_all_duplicates：搜尋資料庫中所有重複的訂單。
get_duplicate_statistics：獲取重複點單的統計分析數據。
update_drink_order / update_order_by_name：修改現有訂單資訊。
delete_drink_order / delete_order_by_name：刪除指定訂單。
角色：負責與 Google Cloud Firestore 連線與執行 CRUD 操作。
功能：
以單例模式（Singleton）管理 Firestore Client，避免重複連線。
透過讀取金鑰檔 firebase-adminsdk.json 進行身份驗證。
提供統一的 firebase_bridge 介面，支援 push (新增)、fetch (讀取)、update (修改)、delete (刪除) 等底層操作。
備份說明：專案中亦包含一個備份版本 db_logic_google.genai.py。
角色：管理菜單與驗證逻辑。
功能：
定義「一沐日」官方的飲品菜單數據 NESTED_MENU 與加料價格 TOPPINGS_MENU。
實作 get_drink_info 與 get_topping_info：使用 RapidFuzz 模糊比對演算法，自動比對口語輸入的飲品名稱（例如：「烏龍綠鮮奶茶」比對出「烏龍綠鮮奶茶」），提升 AI 點單時的精確度與容錯率。
實作 validate_spec：嚴格驗證規格是否同時包含「糖度」與「冰量」資訊。
實作 calculate_price：依據飲品基本價與加料價格計算總金額。
Related MCP server: NTUT iSchoolPlus MCP
為了提升「🌐 內置 AI」模式在行動端（手機、平版）的可用度與性能，我們在 PWA 前端網頁中實作了以下三項核心增強：
功能：下拉選單除了提供 Qwen 2.5 1.5B、Llama 3.2 1B/3B 等內建模型外，新增了 「自訂模型...」 選項。
特色：使用者可直接輸入任何與 WebLLM / MLC-AI 相容的第三方模型 ID（例如：Phi-3-mini-128k-instruct-q4f16_1-MLC），系統將自動串接 Hugging Face CDN 進行背景下載、載入與對話。
功能：自動偵測瀏覽器快取儲存空間（Cache Storage 與 OPFS）。
特色：
智慧顯示：只有在手機/筆電中確實存在已下載的模型快取時，設定面板才會顯示「管理內置 AI 快取模型」控制區；若無快取則自動隱藏，保持介面簡潔。
精準清除：會自動解析並將「自訂模型名稱」也加入清除清單中，支援單選指定模型一鍵刪除以釋放手機空間。
起因：官方 WebLLM 套件限制只有大於 7B/8B 的特定模型才能使用 tools (Function Calling) 參數，否則會直接拋出例外。但 8B 模型體積過大且消耗手機資源。
解決方案：
我們繞過了 WebLLM 的 tools 參數，改用 Prompt-Based 函數呼叫 重新封裝 AI 引擎。
在 systemPrompt 中融入 Few-Shot（少樣本）呼叫範例，強引導 AI 對於點餐、修改、刪除要求直接輸出為 JSON 格式。
前端 app.js 自動攔截該 JSON、執行本地點餐並更新 Firestore 雲端資料庫，最後再將結果餵回給 AI 進行繁體中文總結。
優勢：使僅有 600MB 的 Llama 3.2 1B 或 1.1GB 的 Qwen 2.5 1.5B 也能完美在手機端流暢執行點餐、修改等 MCP 工具，大幅提升下載成功率與對話反應速度！
本專案需要 Python 3.13 以上環境。在執行本專案前，請務必完成以下設定：
建議使用 uv 進行依賴管理與執行：
# 安裝 pyproject.toml 中定義的依賴
uv pip install -r pyproject.toml主要的 Python 套件包括：fastmcp、google-cloud-firestore、google-genai、rapidfuzz、streamlit、anthropic 等。
請前往 Firebase 控制台下載您的服務帳戶金鑰 JSON 檔案。
將其重新命名為 firebase-adminsdk.json 並放置於專案根目錄下（即 c:/aiTest/mcp-drink-main/firebase-adminsdk.json）。
本專案的 db_logic.py 將會自動偵測並載入該金鑰。
請在專案根目錄下建立 .streamlit 資料夾，並於其中建立 secrets.toml 檔案：
# 支援配置多個 AI 廠商金鑰，系統會自動依照您在 secrets.toml 中撰寫的 Key 順序來決定預設使用的雲端 AI！
GEMINI_KEY = "您的_GEMINI_API_KEY" # 啟用 Gemini
OPENAI_KEY = "您的_OPENAI_API_KEY" # 啟用 OpenAI (ChatGPT)
CLAUDE_KEY = "您的_ANTHROPIC_API_KEY" # 啟用 Anthropic (Claude)環境變數支援：亦支援自動讀取系統環境變數（如 GOOGLE_API_KEY、OPENAI_API_KEY、ANTHROPIC_API_KEY），本地 NB 執行時免填設定檔。
本地 Ollama 免金鑰與 CORS 設定：若選擇本地 Ollama 模式，則無需配置任何 API 金鑰，只需在本地執行 Ollama (ollama serve)。
💡 重要提示 (CORS 阻擋問題)：若在網頁端（如 PWA 前端
http://localhost:8000）使用本地 Ollama，必須啟用 CORS 跨來源共用 設定，否則瀏覽器會出於安全考量阻擋連線，造成模型清單一直顯示「載入中...」或「無法連線至本地 Ollama (11434)」。Windows 設定步驟：
在系統工作列右下角右鍵點擊 Ollama 小圖示，選擇 Quit Ollama 徹底關閉程式。
新增 Windows 使用者環境變數：
變數名稱 (N)：
OLLAMA_ORIGINS變數值 (V)：
*重新啟動 Ollama 即可解決。
為了便於您掌握本專案的架構，以下提供了三種執行方式的關聯圖：
graph TD
User([使用者 User])
subgraph ModeA [方式 A：極致現代美學 PWA 前端]
User -->|存取 Port 8000| Browser[手機 PWA / 瀏覽器]
Browser -->|載入靜態資源| HttpServer[Python HTTP Server]
Browser -->|直接讀寫訂單| Firestore[(Cloud Firestore)]
Browser -->|AI 對話與工具解析| AIChat[AI 服務 Gemini/Ollama]
end
subgraph ModeB [方式 B：Streamlit 管理端 UI]
User -->|存取 Port 8501| StreamlitApp[Streamlit 應用 drink_app.py]
StreamlitApp -->|讀寫訂單| Firestore
StreamlitApp -->|AI 對話| AIChat2[AI 服務 Gemini/Ollama]
StreamlitApp -->|內部通訊| McpClient[Stdio MCP Client]
McpClient -->|呼叫點餐/菜單| McpServer1[mcp_server.py]
end
subgraph ModeC [方式 C：Claude Desktop 掛載]
User -->|點餐對話| ClaudeDesktop[Claude Desktop 軟體]
ClaudeDesktop -->|STDIO 協定掛載| McpServer2[mcp_server.py]
McpServer2 -->|執行點餐寫入| Firestore
end這是具有現代毛玻璃美學的極致前端介面，整合了雲端金鑰設定面板，並可於側邊欄切換多款 AI 與本地 Ollama 模型。
您可以透過以下指令啟動本地網頁伺服器：
# 使用虛擬環境的 Python 啟動本地網頁伺服器
.\.venv\Scripts\python.exe -m http.server 8000
# 或使用系統 Python
python -m http.server 8000啟動後，請在瀏覽器開啟 http://localhost:8000。
您可以點擊右上角的 ⚙️ 設定圖示，自行填寫雲端 API 金鑰。
這是基於 Streamlit 的後端數據與管理介面，您可以使用以下任一指令啟動：
# 透過當前虛擬環境執行 Streamlit
.\.venv\Scripts\python.exe -m streamlit run drink_app.py
# 或透過 uv 執行
uv run streamlit run drink_app.py啟動後，瀏覽器會自動開啟 http://localhost:8501。您可以在此處查看到純文字排版的點餐清單與 AI 側邊欄。
您可以將 mcp_server.py 設定到 Claude Desktop 的設定檔中，讓您的 Claude 桌面應用程式直接獲得一沐日點餐的能力：
開啟 Claude Desktop 設定檔：
C:\Users\ch26788\AppData\Roaming\Claude\claude_desktop_config.json
在 mcpServers 下加入 drink-server：
{
"mcpServers": {
"drink-server": {
"command": "C:\\aiTest\\mcp-drink-main\\.venv\\Scripts\\python.exe",
"args": [
"C:\\aiTest\\mcp-drink-main\\mcp_server.py"
],
"env": {
"PYTHONPATH": "C:\\aiTest\\mcp-drink-main"
}
}
}
}重啟 Claude Desktop。在對話框中您應該可以看到 🔧 工具圖標，這代表 Claude 已成功載入一沐日的點餐工具。您可以嘗試輸入：
「透過 drink-server，幫林進源訂一杯粉粿桂花檸檬 無糖去冰 加招牌粉粿」
「幫我看看最近的訂單」
在之前的版本中，當透過 MCP 呼叫 update_order_by_name 或 update_drink_order 時，可能會遇到以下 Pydantic 類型驗證錯誤：
2 validation errors for call[update_order_by_name]
spec input should be a valid string [type=string_type, input_value=None, input_type=NoneType]這是因為參數宣告為 str，但預設值為 None，導致 Pydantic 在解析引數時產生衝突。目前已全面修復，在 mcp_server.py 中：
導入了 from typing import Optional。
將可能為空之參數型別標記為 Optional[str]（例如 spec: Optional[str] = None）。
對 None 值的傳遞進行了安全過濾，確保資料庫更新時不會以 Null 覆蓋原有欄位。
詳細的修復日誌與程式碼對比請參閱 docs/EXECUTIVE_SUMMARY.md 與 docs/BUG_FIX_EXPLANATION.md。
本工作區亦包含非點餐系統核心的股票爬蟲與繪圖工具：
stockChart.py：自 Yahoo 奇摩股市抓取個股（以聯電 2303 為例）的歷史 K 線數據，使用 matplotlib 進行中文化折線圖繪製。
stock_crawler_advanced.py：進階股票數據爬蟲與分析腳本。
刪除指定的點餐訂單。
doc_id: 要刪除的訂單 ID。
| Name | Required | Description | Default |
|---|---|---|---|
| doc_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description alone must convey behavioral traits. It only states that it deletes an order; it does not disclose whether the action is permanent, requires permissions, or what happens if the ID does not exist. This is a significant gap for a destructive operation.
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 very brief and to the point, with the main purpose stated first and the parameter defined immediately after. It wastes no words, though it is minimal and could benefit from more context.
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, output schema, and usage guidance, the description is incomplete. It covers the basic purpose and parameter but omits when to use it, behavioral consequences, and error handling, leaving important gaps for a destructive operation.
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 explains doc_id as 'the ID of the order to delete,' which adds meaning beyond the bare schema definition of a string. Since there is only one parameter and it is clearly defined, it compensates well for the lack of schema descriptions.
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 it deletes a specified drink order, and the inclusion of doc_id indicates the identifier used. It is specific in verb and resource, though it does not explicitly contrast with delete_order_by_name, making the distinction implicit via the parameter.
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 the sibling delete_order_by_name or other tools. The description does not mention any conditions, alternatives, or prerequisites for using this deletion method.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
根據姓名刪除訂單。
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. It only states 'delete orders' without mentioning irreversibility, whether multiple orders are affected, permission requirements, or any side effects. The destructive nature is implied but not explicitly disclosed.
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. It is concise and front-loaded, effectively conveying the core action. It does not waste words, though it could be expanded with important details without becoming verbose.
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?
For a destructive tool with no annotations, the description is incomplete. It does not explain what happens to the deleted orders, whether it deletes all orders matching the name or just one, or any error conditions. The output schema may cover return values, but the description offers no behavioral or safety context. It is minimally viable but lacks necessary depth.
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 has 0% description coverage, but the description does add some semantic meaning: 'by name' clarifies that the 'name' parameter is the matching criterion for deletion. However, it does not specify matching behavior (exact, partial, case-insensitive) or whether it deletes all matches, so it only partially compensates for the lack of schema documentation.
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 (delete) and resource (orders) with a selection criterion (by name). It is specific and understandable, but it does not explicitly differentiate from sibling tools like delete_drink_order, so it lacks the sibling distinction required for a 5.
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 update_order_by_name or delete_drink_order. There is no mention of context, prerequisites, or exclusions, leaving the agent to infer usage entirely from the tool name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
🔍 搜尋特定人物的重複訂單資料。 當使用者詢問「搜尋個人有重複的資料」、「某人有重複訂單」時，請呼叫此工具。
參數說明：
name: 要查詢的人名
功能：
找出該人名下所有訂單
識別重複的訂單（相同飲品、規格、加料）
顯示重複次數和時間戳記
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It transparently explains the behavior: finds all orders under the name, identifies duplicates based on same drink/spec/add-ons, and shows duplicate count and timestamps. It implies read-only via '搜尋' and '找出', though it does not explicitly state no modifications occur.
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 well-structured with an emoji-led summary, trigger examples, parameter explanation, and a function list. It is not overly verbose and front-loads the purpose, though the trigger examples and function list add some length. No wasted words.
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?
The tool is simple (1 parameter, no nested objects) and has an output schema, so the description does not need to explain return values. It covers the operation logic, duplicate matching criteria, and output elements. It lacks explicit alternative tool mentions, but overall the description is complete for its complexity.
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 only defines 'name' as a string with no description, so schema coverage is 0%. The description compensates by stating 'name: 要查詢的人名', giving meaning and context to the parameter. It does not mention input format nuances like exact matching, but it sufficiently explains the purpose.
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 it searches for duplicate order data of a specific person using the verb '搜尋' (search) and the resource '特定人物的重複訂單資料'. It distinguishes from sibling tools like search_all_duplicates by scoping to a specific person, though it does not explicitly mention alternatives.
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 explicit trigger scenarios in Chinese: '當使用者詢問「搜尋個人有重複的資料」、「某人有重複訂單」時，請呼叫此工具'. This tells when to use the tool, but it does not mention when not to use it or compare with sibling tools like search_all_duplicates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
📊 取得重複訂單的統計資訊。 當使用者詢問「重複訂單統計」、「重複率」時，請呼叫此工具。
功能：
計算重複訂單的比例
顯示熱門的重複商品
提供改進建議
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the transparency burden. It describes what the tool does (computes proportions, shows popular items, gives suggestions) but does not explicitly state whether it is read-only, has side effects, or its data scope. The name implies a read operation, but explicit disclosure would be stronger.
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 concise and well-structured: a one-sentence purpose, a trigger condition, and a bulleted list of features. It front-loads the core purpose and every sentence earns its place without redundancy.
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?
For a tool with zero parameters and an output schema, the description provides sufficient context: trigger conditions and expected functionality. It could specify whether statistics are system-wide or scoped, but the simplicity of the tool and existence of an output schema make the current description adequately complete.
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 zero parameters, so the description does not need to explain parameter meanings. The baseline for 0 params is 4, and the description appropriately avoids unnecessary parameter 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: to get statistical information on duplicate orders. It lists specific capabilities (calculate duplicate rate, show popular duplicates, provide suggestions) and distinguishes itself from sibling tools like find_duplicate_orders_by_name or search_all_duplicates by focusing on aggregate statistics rather than individual duplicates.
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 explicitly names trigger phrases ('重複訂單統計', '重複率') that should lead to this tool, providing clear usage contexts. It does not mention when not to use it or name alternative tools, but the trigger guidance is sufficient for basic differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
列出最近的所有訂單資訊，包含 ID、姓名與品項。 刪除或修改訂單前，請先呼叫此工具確認 ID。
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description must carry the full burden. It implies a read-only listing operation and mentions it helps confirm IDs before mutations, but it does not explicitly state whether the tool is read-only, nor does it disclose any side effects, permissions, or return format limitations. The information is adequate but not rich.
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 two concise sentences. The first sentence front-loads the action and output fields; the second adds a practical usage note. There is zero wasted text.
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?
For a simple no-parameter list tool with no output schema, the description adequately explains what is returned (ID, name, items) and why to use it (confirm ID before mutations). It could be slightly more precise about what 'recent' means, but overall it is complete enough.
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 zero parameters, so the schema fully covers parameter semantics (trivially). The description does not need to describe parameters. Per the rubric, 0 params baseline is 4.
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 the resource '最近的所有訂單資訊' (all recent order information), specifying the fields included (ID, name, items). It distinguishes itself from sibling tools like update/delete/duplicate search by being a simple listing operation.
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 explicitly instructs to call this tool before deleting or modifying an order to confirm the ID, providing a clear when-to-use scenario. However, it does not explicitly mention when not to use it or name alternative tools, so it falls slightly short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
執行飲品點餐工具。當使用者表達想喝飲料或點餐時，請呼叫此工具。
參數說明：
name: 訂購人的姓名 (請務必取得姓名)。
drink_name: 飲料名稱 (AI 會自動比對最接近的品項)。
spec: 甜度與冰量。必須包含糖度與冰量資訊 (例如：微糖少冰)。 如果使用者資訊不足，請主動追問。
topping: 加料內容 (如：粉粿、寒天)，若無則預設為『無』。
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| spec | Yes | ||
| topping | No | 無 | |
| drink_name | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses key behavioral traits: drink_name is auto-matched to the closest item, spec must include sugar/ice and missing info should be proactively asked, and topping defaults to '無'. This adds meaningful context beyond the bare schema, though it does not describe the return value or side effects.
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 concise, front-loaded with the tool's purpose, and uses a clear bullet-like structure for parameter explanations. Every sentence contributes value, with no wasted words.
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?
The description covers when to use, parameter semantics, and behavioral matching details. It omits return value or confirmation behavior, but for a simple create-order tool, the outcome is intuitive. Given no output schema exists, a brief note on the response would improve completeness, but it is already adequate for an agent to invoke correctly.
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 no descriptions (0% coverage), but the description fully explains each parameter: name must be obtained, drink_name auto-matches, spec requires sweetness and ice, and topping defaults. This completely compensates for the schema's lack of semantic information.
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 it executes a drink ordering tool and specifies when to call it ('當使用者表達想喝飲料或點餐時'). This distinguishes it from sibling tools that update, delete, or list orders, making its purpose specific and unambiguous.
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?
Explicitly says to use the tool when the user expresses wanting a drink or to order, providing clear context. It does not mention alternatives or exclusions, but the sibling tools (update, delete, list) make the boundaries implicit, so it earns a 4 rather than a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
🔍 掃描全部訂單，找出所有有重複訂單的人物。 當使用者詢問「全局搜尋重複」、「誰有重複訂單」時，請呼叫此工具。
功能：
分析所有訂單
找出所有有重複的人物
顯示重複數量統計
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | 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. It discloses the main behavior—scanning all orders, identifying duplicates, and showing count statistics—which implies a read-only analysis. However, it does not explicitly state that no data is modified, nor does it mention performance, permissions, or limitations.
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 appropriately sized and front-loaded with the core purpose. The trigger phrases are useful for usage guidance. The bullet list slightly repeats the first sentence but remains concise and scannable, so no significant waste.
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 has no parameters, an output schema exists, and the operation is a simple global scan, the description covers the essential context: what it does, when to use it, and what output to expect (duplicate count statistics). Minor gaps include lack of explicit differentiation from sibling tools, but overall it is complete enough for a no-argument scan tool.
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 zero parameters and the schema is empty with 100% coverage. The description does not need to elaborate on parameters; the baseline for no-parameter tools is 4, and nothing in the description contradicts or requires additional parameter semantics.
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 scans all orders and finds all people with duplicate orders (掃描全部訂單，找出所有有重複訂單的人物). It uses a specific verb, resource, and scope, and distinguishes itself from sibling find_duplicate_orders_by_name by emphasizing the global '全部' and '全局搜尋重複' scope.
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 explicitly tells the agent when to call it: when the user asks for global duplicate search or who has duplicate orders (「全局搜尋重複」、「誰有重複訂單」). It provides clear context and trigger phrases, but it does not explicitly mention when not to use it or name alternative tools like find_duplicate_orders_by_name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
修改已存在的訂單。當使用者提供訂單 ID 並要求更改內容時使用。
doc_id: 訂單的唯一 ID (從清單取得)。
其他參數與點餐工具相同，僅輸入需要修改的部分。
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| spec | No | ||
| doc_id | Yes | ||
| topping | No | ||
| drink_name | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does disclose that only the provided fields are updated (partial update behavior) and that doc_id is required. However, it does not mention what happens if the order is not found, whether changes are reversible, or what the response looks like, which are significant gaps 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 concise, front-loaded with the main purpose, and uses a clear bullet list to highlight doc_id and the partial-update guideline. Every sentence provides value, and there is no wasted text.
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, no output schema, and zero parameter documentation in the schema, the description is incomplete. It does not explain return values, error cases, or how this tool differs from update_order_by_name beyond the use of ID. Relying on 'same as the ordering tool' for most parameters weakens independence. Overall, the tool is not fully self-contained for an agent.
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 has no parameter descriptions (schema coverage 0%), so the description must compensate. It explains doc_id ('unique order ID obtained from the list') but refers to all other parameters as 'same as the ordering tool' without specifying their meanings. For a tool with five parameters, this leaves the semantics of name, spec, topping, and drink_name largely unexplained and dependent on another tool's documentation.
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 'Modify an existing order' with a specific verb and resource. It also provides a usage condition ('when the user provides an order ID and requests changes') and distinguishes itself from siblings by requiring doc_id, though it does not explicitly name the alternative update_order_by_name.
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 explicitly states when to use the tool: 'Use when user provides order ID and requests changes.' It also gives guidance on partial updates ('only input the parts that need to be modified'), which clarifies usage. However, it does not explicitly mention when not to use it (e.g., when only name is known), so it lacks an explicit exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
根據姓名修改訂單內容。 參數設為選填（None）以處理使用者說「其餘不變」的情況。
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| spec | No | ||
| topping | No | ||
| drink_name | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It adds useful behavior about optional parameters (None means 'keep unchanged'), but it does not disclose other important traits such as behavior when no matching name is found, whether it updates one or multiple orders, or error handling. This is adequate but incomplete.
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 two sentences: the first gives the purpose, the second adds crucial behavior about optional parameters. It is concise, front-loaded, and every sentence earns its place.
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?
The tool has 4 parameters, no annotations, but an output schema exists. The description covers the core behavior and the None semantics, but lacks details about edge cases (e.g., multiple matches), which fields are updatable, and how to use 'spec'. It is minimally viable but has clear gaps.
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 explains the general optionality semantics (None means no change), but it does not explain what each parameter (spec, topping, drink_name) actually represents. The parameter meanings remain largely ambiguous, especially 'spec', leaving the agent guessing.
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 action: 'modify order content based on name'. This is a specific verb+resource+scope (by name), and it distinguishes from siblings like update_drink_order (likely by ID) and delete_order_by_name (delete vs update).
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 clear context on how to use the tool, especially the optional parameters to handle 'the rest unchanged' scenario. While it doesn't explicitly exclude alternatives, the naming and phrasing imply using it when you want to update an order by customer name, which differentiates it from sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0delete_drink_orderdelete_order_by_namefind_duplicate_orders_by_nameget_duplicate_statisticsget_menulist_recent_ordersplace_drink_ordersearch_all_duplicatesupdate_drink_orderupdate_order_by_nameScored across 10 tools
Each tool has a distinct purpose: listing orders, finding duplicates by name, searching all duplicates, getting duplicate statistics, updating/deleting by ID or by name, fetching the menu, and placing orders. The update and delete pairs are clearly differentiated by the identifier type (doc_id vs. name), and the duplicate tools are distinguished by scope.
Most tools follow a verb_noun pattern (e.g., list_recent_orders, get_menu, place_drink_order), but there are minor inconsistencies such as using both 'find_' and 'search_' for similar duplicate operations, and 'update_drink_order' versus 'update_order_by_name' where the object naming varies. Overall the pattern is readable but not perfectly uniform.
With 10 tools, the server is well-scoped for the drink ordering and duplicate-detection domain. Each tool serves a necessary function, and the count is neither too sparse nor overwhelming.
The tool surface covers the full CRUD lifecycle for orders (place, list, update, delete), includes menu retrieval, and provides comprehensive duplicate detection and statistics. No obvious gaps exist for the intended functionality.
MCP server for AI dialogue using various LLM models via AceDataCloud
MCP server for Sendbird — chat users, channels, members, and messages from your AI client.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
MCP server for Speech-to-Text