目標先講清楚：
針對Anthropic的writing effective tools for ai agents — with agents進行重點筆記，並轉換成實際落地可以用的技巧

Anthropic的文章包含兩個部分：

1. 怎麼開發適合agent使用的工具
2. 工具開發的細節，讓工具跟Agent搭配後更能發揮效益

1. 怎麼開發適合agent使用的工具(How to write tools)

以下五個步驟

Step 1. 建立工具原型-tool+Agent

你不知道工具對agent來說好不好用，只能讓agent試試看

做法：

1. 把工具包成本機 MCP 伺服器或 Desktop extension（DXT）
2. 使用已有的agent(ex. claude code, claude destop app)
3. 不想打包成mcp server，也可以把工具直接帶進 Anthropic API 進行程式化測試。

# pip install anthropic
import os, json, time
from anthropic import Anthropic

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

# 1) 宣告工具（這裡示範一個極簡「查天氣」工具）
tools = [
    {
        "name": "get_weather",
        "description": "查詢某城市今天的天氣摘要（攝氏）。",
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "城市名稱（例如: 台北）"}
            },
            "required": ["city"],
            "additionalProperties": False
        }
    }
]

# 2) 後端實作工具
def get_weather(city: str):
    data = {
        "台北": {"temp_c": 28, "condition": "局部多雲"},
        "東京": {"temp_c": 24, "condition": "晴"},
    }
    # 預設回傳一個簡單的語義結果（對代理可讀）
    info = data.get(city, {"temp_c": 26, "condition": "晴時多雲"})
    return {
        "city": city,
        "summary": f"{city} 今日 {info['condition']}，約 {info['temp_c']}°C"
    }

# 3) 建立對話，送進工具
messages = [
    {"role": "user", "content": "幫我查一下台北今天的天氣，並用一句話總結。"}
]

while True:
    resp = client.messages.create(
        model="claude-3-7-sonnet-20250219",  # 依你可用的最新模型調整
        max_tokens=512,
        tools=tools,
        messages=messages,
        system="你可以使用提供的工具來獲得最新資訊。"
    )

這個階段的目的：

觀察Agent使用工具的回應，收集用戶回饋，將「使用情境與提示（prompts）」更具體化

補充：其實prototype的建議也可以使用openai sdk或langchain的demo code, 任何快速把tool bind到agent的框架都可以

Step 2. 評估 - 設計評估任務

設計任務的方向：

1. 強任務設計

從公司真實流程下手，讓任務逼近現實、需要多步驟與多次工具呼叫：

任務 A：「幫我排下週三與客戶 Jane 的會議，附上上次會議記要（從知識庫抓）、並訂一間 6 人會議室。」
任務 B：「客戶 9182 申訴被重複扣款三次，請查付款日誌、確認是否還有其他受影響客戶，並輸出結論。」
任務 C：「找到 Sarah Chen 的退訂，產出保留方案：離開原因、最有說服力的優惠、以及風險。」

2. 弱任務設計

讓代理只要一次呼叫或過度簡化（例如僅搜尋單一ID）

3. 任務設計後，事先預期Agent會用哪些工具，衡量代理是否理解工具用途

這個階段的目的：

每個評測任務的設計，都要有可驗證的結果

Step 3. 評估 - 執行評估、收集結果

做法

1. 創建評估Aagent

模型跟Prototype的Agent相同，但是在原本的system prompt需要加上「思考摘要/決策理由/評分 JSON」

# Prototype的system prompt

你是旅遊助理。可以用提供的工具完成任務。
原則：1) 回答要面向用戶 2) 不要輸出你的中間想法或內部日誌。
若需多次查詢，自己決定工具參數並整合成簡潔答案。

只給對用戶的結論；不露出推理

# 系統提示

你是評測任務的 agent。可使用工具完成任務，並在每個回合輸出兩段：
[THINK] 簡述決策：為何/如何選參數、下一步計畫（最多 5 行）。
[ANSWER] 只面向「最終用戶」的答案（可被直接顯示）。
若工具失敗或資料不足，在 [THINK] 中記錄原因與改進。
最後請輸出一段 JSON { "price_ceiling_ok": bool, "has_baggage": bool } 供評分器使用。

多了 [THINK] 決策摘要 與 可機器判分的 JSON；方便你偵錯、計分、做回歸比較。在真實產品裡，這段通常不會呈現給使用者。

2. 指標收集包含：結果、單次工具與整體任務的總執行時間、工具呼叫數、tokens 消耗、錯誤率等。

Step 4. 評估 - 觀察、分析結果

分析的部分涵蓋代理使用工具的整個流程：

做法：

1. 觀察代理卡關或困惑的地方。
2. 閱讀評測代理（evaluation agents）的推理與回饋（或 CoT）
3. 同時也要檢視原始對話逐字稿（含工具呼叫與回應），以捕捉那些不在推理文本裡、但實際上發生的行為

Step 5. 改進工具（使用Claude code為例)

做法：

把一批評測逐字稿（含：系統提示、使用者任務、工具呼叫/回應、代理的想法與回饋）接在一起貼給 Claude Code，請它「總結問題 → 提改動 PR」。

範本：

下面是 8 個失敗/邊緣案例的逐字稿。請你(claude code)：

1. 彙整失敗原因（以次數排序）。
2. 直接重寫 search_flights 的工具描述與 input_schema，確保能避免這些錯誤。
3. 調整預設值（如 limit）、加上 response_format（concise|detailed）、以及錯誤訊息的 hint。
4. 產出 3 個「正/誤」對照範例。
5. 回傳一份 Changelog（列出你改了什麼＆為什麼）。

2. 工具開發的細節，讓工具跟Agent搭配後更能發揮效益(Principles for writing ef fective tools)

1) 選對要做（與不要做）的工具

• 錯誤做法：把現有軟體功能或 API 端點直接包一層做成工具——不論這些工具是否真的適合給代理（agent）使用。

• 壞例子（容易浪費上下文）

  • list_contacts()：一次吐出 5 萬筆聯絡人，讓模型自己慢慢翻。

  電腦記憶體相對便宜又充足，但LLM 代理的「上下文容量」有限，如果tool輸出太雜的東西，會把token浪費在看不重要的資料上

• 好例子（直接對齊任務）

• search_contacts(query, limit)：只回「最可能的幾筆」。

• schedule_event(participants, agenda, slots)：把「找空檔＋發邀請」合成一個工具。

• get_traveler_context(customer_id)：一次彙整旅客近期訂單、未付費用與偏好。

2) 用命名空間（namespacing）劃清邊界

給工具加前/後綴，讓代理一眼知道要用哪一個，減少重疊與混淆。

• 做法

  • 依「服務」：asana_search_tasks、jira_search_issues
  • 依「資源」：gds_flights_search、gds_hotels_search

  這個做法，Manus ai 也有使用

3) 從工具回傳「有意義的上下文」

回傳有助後續Agent 決策/行動的語義資訊，避免灌一堆技術 ID。

• 壞例子

{"uuid":"9f1…","mime_type":"application/json","256px_image_url":"…"}

• 好例子（語義優先＋可串接）

{
  "customer_name": "王小美",
  "upcoming_trip": {"route":"TPE→NRT","dates":"2025-11-05/09"},
  "unpaid_balance": 1200,
  "contact_options": [{"type":"email","value":"mei@example.com","id":12345}]
}

4) 為 Token 效率最佳化回應

優化工具回傳給代理（agent）的上下文token總數也很重要

• 做法清單

  • limit、page_token、date_range 等參數預設保守，讓token不會超過限制
  • 支援 response_format（"concise"/"detailed"），預設精簡。
  • 截斷時在回應中明說如何要求更多（例如「可設定 page_token 取得下一頁」）。
  • 驗證失敗時回「怎麼修」而不是 500/堆 stack trace。

關於錯誤處理的回覆可以參考Day 14｜Agent Design - Tools - Error Handling（3/3）

5) 用「提示工程」寫工具描述與規格

清楚描述工具的資訊，包含使用情境、使用方式、目的等。

• 壞描述

Search users. Params: `user` (string)

• 好描述

**Purpose**：在 CRM 中以「姓名或電郵」找業務聯絡人，用於後續寄信或建立會議。
**Inputs**：

* `query`（string）：姓名或 email，支援前綴比對；**不要**傳入多個逗號分隔關鍵字。
* `max_results`（int，預設 5）
  **Outputs (concise)**：`[{name,email,title}]`
  **Outputs (detailed)**：同上外加 `contact_id`（供 `crm_send_email(contact_id, …)` 使用）
  **Notes**：若只知道名字且很常見，先用 `department` 或 `company` 關鍵字縮小範圍。
  **Examples**：`{"query":"mei@example.com"}`、`{"query":"王小美", "max_results":3}`
  **Validation**：若 `query` < 2 字元，回 `error.hint="請提供更具體的姓名或 email"`。

關於如何管理Tool的Prompt可以參考Day 12｜Agent Design - Tools - LangChain tool技巧

接下來要做什麼

分享針對OpenAI在DevDay 2025推出的Apps SDK，是我覺得很酷的MCP應用，因此透過挑戰的機會，去分析了解

參考資源

1.Writing effective tools for agents — with agents