前面幾天我們已經做過不少 MCP Tool，從 Calculator、File System、SQLite，到 REST API 等，做到這裡可以發現，Tool 能執行不代表 Tool 就設計得好，今天就回頭整理幾個設計 Tool 時值得注意的地方。

Tool 名稱要清楚

先看看之前的 File System MCP：

list_files
search_files
read_file

光看名稱就能知道大概的用途。

相反地：

tool1
file_tool
do_something

就很難判斷到底可以做什麼，所以名稱最好直接描述功能，例如：

search_files
get_students
get_weather

Tool 描述要明確

Tool 除了名稱之外，也應該提供清楚的描述。

例如：

@mcp.tool()
def search_files(keyword: str) -> str:
    """搜尋檔案內容中的關鍵字。"""

這樣 Agent 可以知道這個 Tool 是搜尋檔案內容，而且需要一個關鍵字，描述不需要很長，但要讓用途清楚。

參數不要太複雜

例如 Calculator：

def calculator(
    a: float,
    b: float,
    operation: str
):

每個參數都有明確用途：

a          → 第一個數字
b          → 第二個數字
operation  → 運算方式

設計 Tool 時，可以盡量做到：

• 參數名稱清楚
• 型別明確
• 不需要的參數不要放進來

簡單的 Tool 就不要設計成需要一大堆參數。

一個 Tool 有明確的目的

File System 就是一個很好的例子：

list_files
search_files
read_file

而不是全部塞進一個：

file_tool

這樣 Agent 才比較容易根據需求選擇適合的 Tool。

例如：

有哪些檔案？
    ↓
list_files

找出包含 MCP 的檔案
    ↓
search_files

讀取 notes.txt
    ↓
read_file

重點不是 Tool 越小越好，而是：

每個 Tool 都應該有清楚的功能目的。

回傳結果要容易理解

Tool 執行成功後，回傳的內容也會直接交給 Agent 使用。

例如：

123,王小明,資工系
124,陳小華,資管系

如果資料比較複雜，適當整理格式會更容易處理：

學號：123
姓名：王小明
系所：資工系

學號：124
姓名：陳小華
系所：資管系

因此設計 Tool 時，不只要考慮，Tool 能不能執行？也要考慮 Agent 拿到結果後好不好使用？

錯誤訊息要有意義

Tool 發生錯誤時，也不要只回傳 Error，至少要有找不到檔案 notes.txt，或是除數不能為 0 之類的提示，讓 Agent 知道實際發生什麼事情，才有機會做出適當的處理。

回頭檢查我們做過的 Tool

前面做過的 Tool，都可以用這幾個問題重新檢查：

• 名稱看得懂嗎？
• 描述清楚嗎？
• 參數是否合理？
• 功能是否有明確目的？
• 回傳結果是否容易使用？
• 錯誤訊息是否有意義？

這些看起來都是小地方，但當 MCP Tool 越來越多時，設計好不好就會開始明顯影響 Agent 的使用效果。

結語

做到現在，我們已經不只是把一個個 Tool 做出來，而是開始思考 Agent 要怎麼使用這些 Tool，一個好的 MCP Tool，不只是功能能正常執行，而是要讓 Agent 能夠清楚理解它的用途、正確提供參數，並且有效利用執行結果。

這也是 MCP 很重要的一個地方，我們不是單純在寫 Function，而是在設計一個讓 Agent 可以使用的介面，當 Tool 越來越多，好的設計就會越來越重要，而這些 Tool 最後也會慢慢組合起來，成為 Agent 真正可以完成工作的能力。