Agent不聽話、總犯錯？Claude官方開發指南：手把手教你打造高效工具，讓大模型秒變“靠譜員工”

Anthropic 這篇《Writing effective tools for AI agents — with agents》把給智能體寫工具從零散經驗上升為可復現的方法論：強調以評估驅動的迭代流程、以Agents為中心的工具設計原則（namespacing、簡潔響應、token 效率等），并展示用 Claude 自身去分析/優化工具的實戰路徑——這對工程落地、產品設計和行業標準化都具有立刻可用的價值

過去我們把 API 當成給程序員用的契約，現在要把接口重新設計成能被會思考的模型理解的工具。Anthropic 這篇工程帖子，把這件事從經驗總結，推演成一套可執行的工程流程——從原型、評估、到讓 Claude 自己參與改進工具。讀完它，你會發現：未來的后端接口設計，不再只為了機器——而是為了會推理的機器

Agent的效能取決于提供給它們的工具。本文將分享如何編寫高質量的工具和評估方法，以及如何利用 Claude 來為它自己優化工具，從而提升性能

模型上下文協議（Model Context Protocol, MCP）可以為大語言模型代理賦予數百種工具來解決現實世界的任務。但如何使這些工具的效能最大化呢？

本文將介紹在多種代理 AI 系統中提升性能最有效的技巧

首先，本文將涵蓋如何：

1.構建和測試工具的原型

2.創建并運行針對代理使用工具的全面評估

3.與像 Claude Code 這樣的代理協作，自動提升工具的性能

最后，本文將總結在此過程中總結出的編寫高質量工具的關鍵原則：

選擇正確的工具進行實現（以及不實現）

通過命名空間為工具定義清晰的功能邊界

從工具向代理返回有意義的上下文

優化工具響應的詞元（token）效率

通過提示工程優化工具描述和規范

什么是工具？

在計算領域，確定性系統在給定相同輸入時總是產生相同的輸出，而非確定性系統——比如代理——即使在起始條件相同的情況下也可能生成不同的響應。

在傳統軟件編寫中，是在確定性系統之間建立一種契約。例如，像 getWeather("NYC") 這樣的函數調用，每次執行時都會以完全相同的方式獲取紐約市的天氣。

工具是一種新型軟件，它反映了確定性系統與非確定性代理之間的契約。當用戶問“我今天需要帶傘嗎？”，代理可能會調用天氣工具，也可能根據常識回答，甚至可能先詢問地點等澄清性問題。偶爾，代理可能會產生幻覺，或者無法理解如何使用某個工具。

這意味著在為代理編寫軟件時，需要從根本上反思方法：不能像為其他開發者或系統編寫函數和 API 那樣來編寫工具和 MCP 服務器，而是需要為代理進行設計。

目標是通過使用工具來追求各種成功的策略，從而擴大代理能夠有效解決各類任務的范圍。幸運的是，根據經驗，那些對代理而言最“易于使用”的工具，最終對人類來說也出乎意料地直觀易懂。

如何編寫工具

本節將介紹如何與代理協作來編寫并改進提供給它們的工具。首先，快速搭建一個工具原型并在本地進行測試。接著，運行一次全面的評估來衡量后續的改動效果。通過與代理協同工作，可以重復評估和改進工具的流程，直到代理在真實世界任務上取得優異的性能。

構建原型

在沒有親身實踐的情況下，很難預見哪些工具對代理來說是易于使用的，哪些不是。首先應快速搭建一個工具原型。如果使用 Claude Code 編寫工具（可能是一次性生成），向 Claude 提供工具所依賴的任何軟件庫、API 或 SDK（可能包括 MCP SDK）的文檔會很有幫助。大語言模型友好的文檔通常可以在官方文檔網站的扁平化 llms.txt 文件中找到。

將工具包裝在本地 MCP 服務器或桌面擴展（DXT）中，就可以在 Claude Code 或 Claude 桌面應用中連接并測試工具。

要將本地 MCP 服務器連接到 Claude Code，運行 claude mcp add [args...]

要將本地 MCP 服務器或 DXT 連接到 Claude 桌面應用，分別導航至“設置 > 開發者”或“設置 > 擴展”

工具也可以直接傳遞到 Anthropic API 調用中進行編程化測試

親自測試這些工具，找出任何不順手的地方。收集用戶的反饋，以便對工具所要支持的用例和提示建立直觀的理解。

運行評估

接下來，需要通過運行評估來衡量 Claude 使用工具的效果。首先，基于真實世界用例生成大量的評估任務。建議與代理協作，幫助分析結果并確定如何改進工具

生成評估任務

利用早期原型，Claude Code 可以快速探索工具并創建數十個提示和響應對。提示應受到真實世界用例的啟發，并基于現實的數據源和服務（例如，內部知識庫和微服務）。建議避免使用過于簡單或膚淺的“沙盒”環境，因為它們無法以足夠的復雜性對工具進行壓力測試。一個好的評估任務可能需要多次工具調用——甚至可能多達數十次

以下是一些好的任務示例：

安排下周與 Jane 開會，討論最新的 Acme 公司項目。附上我們上次項目規劃會議的紀要，并預訂一間會議室

客戶 ID 9182 報告稱，他們的一次購買嘗試被收取了三次費用。找出所有相關的日志條目，并確定是否有其他客戶受到同樣問題的影響

客戶 Sarah Chen 剛剛提交了取消請求。準備一份挽留方案。確定：(1) 他們離開的原因，(2) 哪種挽留方案最具吸引力，以及 (3) 在提出方案前需要注意的任何風險因素。

以下是一些較弱的任務示例：

安排下周與 jane@acme.corp 開會

在支付日志中搜索 purchase_complete 和 customer_id=9182

根據客戶 ID 45892 查找取消請求

每個評估提示都應配有一個可驗證的響應或結果。驗證器可以像基準真相與采樣響應之間的精確字符串比較一樣簡單，也可以像讓 Claude 來評判響應一樣高級。避免使用過于嚴格的驗證器，它們可能會因為格式、標點或有效的替代表述等無關緊要的差異而拒絕正確的響應。

對于每個提示-響應對，可以選擇性地指定期望代理在解決任務時調用的工具，以衡量代理在評估過程中是否成功掌握了每個工具的用途。然而，由于解決任務可能存在多種有效路徑，應盡量避免過度指定或對特定策略過擬合。

運行評估

建議通過直接調用 LLM API 以編程方式運行評估。使用簡單的代理循環（包裹著交替的 LLM API 和工具調用的 while 循環）：每個評估任務一個循環。每個評估代理都應被賦予一個任務提示和相應的工具。

在評估代理的系統提示中，建議不僅指示代理輸出結構化的響應塊（用于驗證），還要輸出推理和反饋塊。指示代理在工具調用和響應塊之前輸出這些內容，可能會觸發思維鏈（CoT）行為，從而提高大語言模型的有效智能

如果使用 Claude 運行評估，可以開啟“交錯思考”（interleaved thinking）功能以獲得類似的效果。這將有助于探查代理調用或不調用某些工具的原因，并突出工具描述和規范中需要改進的具體方面。

除了頂層準確率外，還建議收集其他指標，如單個工具調用和任務的總運行時間、總工具調用次數、總詞元消耗量和工具錯誤。跟蹤工具調用可以揭示代理常用的工作流程，并為工具的整合提供一些機會

分析結果

代理是發現問題和提供反饋的得力助手，它們能就從矛盾的工具描述到低效的工具實現和令人困惑的工具模式等一切問題提供反饋。但請記住，代理在反饋和響應中遺漏的內容往往比它們包含的內容更重要。大語言模型并不總能言如其意。

觀察代理在何處遇到困難或感到困惑。通讀評估代理的推理和反饋（或思維鏈），以找出不順手的地方。審查原始交互記錄（包括工具調用和工具響應），以捕捉代理思維鏈中未明確描述的任何行為。要讀懂言外之意；記住，評估代理不一定知道正確的答案和策略。

分析工具調用指標。大量的冗余工具調用可能表明需要調整分頁或詞元限制參數；大量因參數無效導致的工具錯誤可能表明工具需要更清晰的描述或更好的示例。在推出 Claude 的網絡搜索工具時，發現 Claude 會不必要地將“2025”附加到工具的查詢參數中，這導致搜索結果出現偏差并降低了性能（通過改進工具描述引導 Claude 回到了正確的方向）。

與代理協作

甚至可以讓代理來分析結果并改進工具。只需將評估代理的交互記錄拼接起來，然后粘貼到 Claude Code 中。Claude 是分析交互記錄和一次性重構大量工具的專家——例如，在進行新更改時，確保工具的實現和描述保持自洽。

實際上，本文中的大部分建議都來自于反復使用 Claude Code 優化內部工具實現的過程。這些評估建立在內部工作空間之上，反映了內部工作流程的復雜性，包括真實的項目、文檔和消息。

通過使用獨立的測試集來確保沒有對“訓練”用的評估集過擬合。這些測試集表明，即使是基于“專家”編寫的工具實現——無論是研究員手動編寫的還是由 Claude 自己生成的——也仍然可以獲得額外的性能提升。

編寫高效工具的原則

本節將把所學到的經驗提煉為幾個編寫高效工具的指導原則。

為代理選擇正確的工具

更多的工具并不總能帶來更好的結果。一個常見的錯誤是，工具僅僅是對現有軟件功能或 API 端點的簡單包裝——而不管這些工具是否適合代理。這是因為代理相對于傳統軟件有不同的“功能可見性”（affordances）——也就是說，它們感知其可以采取的潛在行動的方式不同。

大語言模型代理的“上下文”（即它們一次能處理的信息量）是有限的，而計算機內存則廉價且充足。考慮在地址簿中搜索聯系人的任務。傳統軟件程序可以高效地存儲和逐個處理聯系人列表，檢查完一個再移至下一個。

然而，如果一個大語言模型代理使用的工具返回了所有聯系人，然后它必須逐個詞元地閱讀每個聯系人，那么它就是在不相關的信息上浪費其有限的上下文空間（想象一下通過從頭到尾閱讀每一頁來在地址簿中查找聯系人——也就是通過暴力搜索）。更好、更自然的方法（對代理和人類都一樣）是先跳到相關的頁面（也許是按字母順序查找）。

建議先構建少數幾個經過深思熟慮的工具，針對特定的高影響力工作流程，這些工作流程應與評估任務相匹配，然后在此基礎上逐步擴展。在地址簿的例子中，可以選擇實現一個 search_contacts 或 message_contact 工具，而不是一個 list_contacts 工具。

工具可以整合功能，在底層處理可能多個離散的操作（或 API 調用）。例如，工具可以用相關的元數據豐富工具響應，或者在一個工具調用中處理頻繁鏈式調用的多步任務。

以下是一些示例：

與其實現 list_users、list_events 和 create_event 工具，不如考慮實現一個 schedule_event 工具，該工具可以查找空閑時間并安排事件

與其實現一個 read_logs 工具，不如考慮實現一個 search_logs 工具，它只返回相關的日志行和一些上下文

與其實現 get_customer_by_id、list_transactions 和 list_notes 工具，不如實現一個 get_customer_context 工具，該工具一次性匯編客戶所有近期和相關的信息。

確保構建的每個工具都有一個清晰、獨特的目的。工具應能讓代理像人類在擁有相同底層資源的情況下那樣，對任務進行細分和解決，并同時減少本應被中間輸出消耗的上下文。

過多的工具或功能重疊的工具也可能分散代理的注意力，使其無法采取高效的策略。謹慎、有選擇地規劃要構建（或不構建）的工具，可以帶來巨大的回報。

為工具使用命名空間

AI 代理可能會接觸到數十個 MCP 服務器和數百個不同的工具——包括其他開發者開發的工具。當工具功能重疊或目的模糊時，代理可能會混淆該使用哪個。

命名空間（將相關工具按共同的前綴分組）有助于在眾多工具之間劃定界限；MCP 客戶端有時會默認這樣做。例如，按服務（如 asana_search、jira_search）和按資源（如 asana_projects_search、asana_users_search）對工具進行命名空間劃分，可以幫助代理在正確的時間選擇正確的工具。

實踐發現，選擇基于前綴還是后綴的命名空間方案，對工具使用評估有不可忽視的影響。這種影響因大語言模型而異，建議根據自己的評估選擇命名方案。

代理可能會調用錯誤的工具，用錯誤的參數調用正確的工具，調用過少的工具，或錯誤地處理工具響應。通過有選擇地實現其名稱能反映任務自然劃分的工具，可以同時減少加載到代理上下文中的工具和工具描述的數量，并將代理計算從代理的上下文中轉移回工具調用本身。這降低了代理犯錯的總體風險。

從工具中返回有意義的上下文

同樣地，工具的實現應注意只向代理返回高信息量的信號。它們應優先考慮上下文相關性而非靈活性，并避免使用低級別的技術標識符（例如：uuid、256px_image_url、mime_type）。像 name、image_url 和 file_type 這樣的字段更有可能直接為代理的后續行動和響應提供信息。

代理處理自然語言名稱、術語或標識符時，也比處理晦澀的標識符要成功得多。實踐發現，僅僅將任意的字母數字 UUID 解析為更具語義意義和可解釋性的語言（甚至是 0 索引的 ID 方案），就能通過減少幻覺顯著提高 Claude 在檢索任務中的精確度。

在某些情況下，代理可能需要靈活地與自然語言和技術標識符輸出進行交互，哪怕只是為了觸發后續的工具調用（例如，search_user(name=’jane’) → send_message(id=12345)）。可以通過在工具中暴露一個簡單的 response_format 枚舉參數來實現這一點，讓代理控制工具是返回“簡潔”還是“詳細”的響應。

可以添加更多格式以獲得更大的靈活性，類似于 GraphQL，可以選擇確切地想要接收哪些信息。以下是一個用于控制工具響應詳細程度的 ResponseFormat 枚舉示例：

enum ResponseFormat {    DETAILED = "detailed",    CONCISE = "concise" }

這是一個詳細工具響應的示例（206 個詞元）：

這是一個簡潔工具響應的示例（72 個詞元）：

即使是工具的響應結構——例如 XML、JSON 或 Markdown——也可能對評估性能產生影響：沒有一種萬能的解決方案。這是因為大語言模型是基于下一個詞元預測進行訓練的，它們往往在處理與其訓練數據格式相匹配的格式時表現更好。最佳的響應結構會因任務和代理的不同而有很大差異。建議根據自己的評估選擇最佳的響應結構。

優化工具響應的詞元效率

優化上下文的質量很重要，但優化工具響應中返回給代理的上下文數量也同樣重要。

建議為任何可能消耗大量上下文的工具響應，實施分頁、范圍選擇、過濾和/或截斷的組合，并設置合理的默認參數值。對于 Claude Code，工具響應默認限制在 25,000 個詞元。預計代理的有效上下文長度會隨著時間的推移而增長，但對上下文高效的工具的需求將持續存在。

如果選擇截斷響應，請務必用有用的指令來引導代理。可以直接鼓勵代理采取更節省詞元的策略，例如在知識檢索任務中進行多次小范圍、有針對性的搜索，而不是一次大范圍的搜索。同樣，如果工具調用引發錯誤（例如，在輸入驗證期間），可以通過提示工程優化錯誤響應，以清晰地傳達具體且可操作的改進建議，而不是返回不透明的錯誤代碼或追溯信息。

這是一個截斷工具響應的示例：

這是一個無益的錯誤響應示例：

這是一個有益的錯誤響應示例：

通過提示工程優化工具描述

現在介紹一種最有效的工具改進方法：通過提示工程優化工具的描述和規范。因為這些內容會被加載到代理的上下文中，它們可以共同引導代理采取有效的工具調用行為。

在編寫工具描述和規范時，可以想象一下如何向團隊中的新成員描述這個工具。考慮那些可能隱含的背景信息——專門的查詢格式、小眾術語的定義、底層資源之間的關系——并將它們明確化。通過清晰地描述（并用嚴格的數據模型強制執行）預期的輸入和輸出來避免歧義。特別是，輸入參數應被明確命名：與其使用名為 user 的參數，不如嘗試使用名為 user_id 的參數。

通過評估，可以更有信心地衡量提示工程帶來的影響。即使是對工具描述進行微小的改進，也可能帶來顯著的性能提升。在對工具描述進行精確優化后，Claude Sonnet 3.5 在 SWE-bench Verified 評估中取得了業界領先的性能，錯誤率大幅降低，任務完成率顯著提高。

可以在開發者指南中找到有關工具定義的其他最佳實踐。如果正在為 Claude 構建工具，也建議閱讀關于工具如何動態加載到 Claude 系統提示中的內容。最后，如果正在為 MCP 服務器編寫工具，工具注解有助于說明哪些工具需要訪問開放世界或會進行破壞性更改。

展望未來

要為代理構建有效的工具，需要將軟件開發實踐從可預測的、確定性的模式轉向非確定性的模式。

通過本文描述的迭代、評估驅動的流程，已經識別出成功工具的一致模式：有效的工具目標明確、定義清晰，能明智地使用代理上下文，可以組合成多樣化的工作流程，并能讓代理直觀地解決真實世界的任務。

未來，預計代理與世界交互的具體機制將會演變——從 MCP 協議的更新到基礎大語言模型本身的升級。通過系統化、評估驅動的方法來改進代理工具，可以確保隨著代理能力的增強，它們使用的工具也將與之共同進化

參考：

https://www.anthropic.com/engineering/writing-tools-for-agents