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

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

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

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

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

首先，本文將涵蓋如何：

1.構(gòu)建和測試工具的原型

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

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

最后，本文將總結(jié)在此過程中總結(jié)出的編寫高質(zhì)量工具的關(guān)鍵原則：

選擇正確的工具進行實現(xiàn)（以及不實現(xiàn)）

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

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

優(yōu)化工具響應(yīng)的詞元（token）效率

通過提示工程優(yōu)化工具描述和規(guī)范

什么是工具？

在計算領(lǐng)域，確定性系統(tǒng)在給定相同輸入時總是產(chǎn)生相同的輸出，而非確定性系統(tǒng)——比如代理——即使在起始條件相同的情況下也可能生成不同的響應(yīng)。

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

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

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

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

如何編寫工具

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

構(gòu)建原型

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

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

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

要將本地 MCP 服務(wù)器或 DXT 連接到 Claude 桌面應(yīng)用，分別導(dǎo)航至“設(shè)置 > 開發(fā)者”或“設(shè)置 > 擴展”

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

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

運行評估

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

生成評估任務(wù)

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

以下是一些好的任務(wù)示例：

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

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

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

以下是一些較弱的任務(wù)示例：

安排下周與 [email protected] 開會

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

根據(jù)客戶 ID 45892 查找取消請求

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

對于每個提示-響應(yīng)對，可以選擇性地指定期望代理在解決任務(wù)時調(diào)用的工具，以衡量代理在評估過程中是否成功掌握了每個工具的用途。然而，由于解決任務(wù)可能存在多種有效路徑，應(yīng)盡量避免過度指定或?qū)μ囟ú呗赃^擬合。

運行評估

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

在評估代理的系統(tǒng)提示中，建議不僅指示代理輸出結(jié)構(gòu)化的響應(yīng)塊（用于驗證），還要輸出推理和反饋塊。指示代理在工具調(diào)用和響應(yīng)塊之前輸出這些內(nèi)容，可能會觸發(fā)思維鏈（CoT）行為，從而提高大語言模型的有效智能

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

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

分析結(jié)果

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

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

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

與代理協(xié)作

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

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

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

編寫高效工具的原則

本節(jié)將把所學(xué)到的經(jīng)驗提煉為幾個編寫高效工具的指導(dǎo)原則。

為代理選擇正確的工具

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

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

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

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

工具可以整合功能，在底層處理可能多個離散的操作（或 API 調(diào)用）。例如，工具可以用相關(guān)的元數(shù)據(jù)豐富工具響應(yīng)，或者在一個工具調(diào)用中處理頻繁鏈式調(diào)用的多步任務(wù)。

以下是一些示例：

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

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

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

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

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

為工具使用命名空間

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

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

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

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

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

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

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

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

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

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

這是一個詳細工具響應(yīng)的示例（206 個詞元）：

這是一個簡潔工具響應(yīng)的示例（72 個詞元）：

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

優(yōu)化工具響應(yīng)的詞元效率

優(yōu)化上下文的質(zhì)量很重要，但優(yōu)化工具響應(yīng)中返回給代理的上下文數(shù)量也同樣重要。

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

如果選擇截斷響應(yīng)，請務(wù)必用有用的指令來引導(dǎo)代理?？梢灾苯庸膭畲聿扇「?jié)省詞元的策略，例如在知識檢索任務(wù)中進行多次小范圍、有針對性的搜索，而不是一次大范圍的搜索。同樣，如果工具調(diào)用引發(fā)錯誤（例如，在輸入驗證期間），可以通過提示工程優(yōu)化錯誤響應(yīng)，以清晰地傳達具體且可操作的改進建議，而不是返回不透明的錯誤代碼或追溯信息。

這是一個截斷工具響應(yīng)的示例：

這是一個無益的錯誤響應(yīng)示例：

這是一個有益的錯誤響應(yīng)示例：

通過提示工程優(yōu)化工具描述

現(xiàn)在介紹一種最有效的工具改進方法：通過提示工程優(yōu)化工具的描述和規(guī)范。因為這些內(nèi)容會被加載到代理的上下文中，它們可以共同引導(dǎo)代理采取有效的工具調(diào)用行為。

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

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

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

展望未來

要為代理構(gòu)建有效的工具，需要將軟件開發(fā)實踐從可預(yù)測的、確定性的模式轉(zhuǎn)向非確定性的模式。

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

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

參考：

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