返回资讯中心
外部精选
软件工程
#开发者实时流

文章总结OpenAI、Anthropic、Google与MCP规范的AI工具设计建议

来源标题:Writing Effective Tools for Agents

一篇技术文章梳理了OpenAI、Anthropic、Google及MCP规范对AI agent工具设计的建议。文章指出工具决定了agent能看到什么、能改变什么,以及剩余多少上下文用于思考,同一模型配不同工具会表现迥异。文中还讨论了工具数量超过20个后的扩展方式,以及保障生产环境中工具调用安全的架构。

Hacker News 最新collinstonui2026/11/13 · 4 天前30 分钟阅读

以下正文同步自 Hacker News 最新,版权归原站所有,已转换为易读排版。

Nov 13, 2026 · @Collins / Systems, AI, Agents, MCP

Tools decide what an AI agent can see and do. What OpenAI, Anthropic, Google and the MCP spec recommend for tool design, how to scale past 20 tools, and the architecture that keeps tool calls safe in production.

Every AI agent is a model plus its tools. The model gets most of the attention: which one to pick, which benchmark it tops. The tools usually get written in an afternoon, by wrapping whatever API already exists. Yet the tools decide what an agent can see, what it can change, and how much of its context is left for thinking. Two agents on the same model can behave completely differently because of the tools they’re given.

A tool is any capability you hand to a model: a function in your code, a call to an external API, a database query, a shell command, even another agent. What every tool shares is its caller. That caller is a model. It reads every word of your tool’s description, every token you return fills its context, it can’t stop to ask what you meant, and it can be talked into following instructions hidden in the data a tool returns. This post is about designing for that caller: what OpenAI, Anthropic, Google and the MCP spec recommend, and what their guides leave out.

The vendors’ guidance keeps coming back to the same test. OpenAI calls it the intern test: could a new person use the function correctly with only what the model sees? Anthropic says to describe a tool the way you’d describe it to a new hire, making implicit context explicit. Google’s version is shorter: “Be extremely clear and specific in your descriptions.”

Most of the rules below follow from that test.

A common mistake is wrapping every API endpoint as a tool. Anthropic puts it plainly: “More tools don’t always lead to better outcomes.” Its examples are a search_contacts tool instead of list_contacts, and a schedule_event tool that finds availability and books the meeting in one step, instead of making the model chain the calls itself.

OpenAI makes the same point in two rules: “Combine functions that are always called in sequence,” and “Don’t make the model fill arguments you already know.” If your code already knows the user ID, don’t ask the model for it.

ENDPOINT WRAPPERSModelYour APIlist_customersget_customerlist_ordersget_ordercreate_refund5 round trips · 5 results to readWORKFLOW TOOLSModelYour toolfind_customer(query)name, plan, recent ordersrefund_order(ref, reason)check policyrefundlogconfirmation2 round trips · the tool chains the rest

Figure 1. The same refund, designed two ways. Dashed orange arrows are results the model has to read.

How many tools is too many?

The vendors give different numbers, and the differences are instructive:

0510152025+active toolsGoogle Gemini“a maximum of 10–20”OpenAI function calling“fewer than 20”, a soft limitOpenAI agent guideoverlap matters more than count< 10 overlapping: some struggle> 15 distinct: some succeed

Figure 2. Recommended active tools per turn, from Google, OpenAI’s docs and OpenAI’s agent guide.

The last row is the important one. Overlap hurts more than count. Two tools that both sound like they search customers will cause more wrong calls than twenty tools with clearly separate jobs. Before splitting work into a new agent, OpenAI recommends improving tool names, parameters and descriptions first.

Tool definitions also take up context before the user says a word. GitHub’s MCP server used to enable 101 tools by default, using 64.6k tokens. In October 2025, GitHub cut the default to 52 tools and 30.3k tokens, citing “tool selection degradation: LLMs struggle to choose the right tool from too many options.” Anthropic reports a five-server setup with 58 tools taking about 55K tokens up front, and says it has seen definitions reach 134K tokens before optimization.

050K100Ktokens before the first messageLargest set seen by Anthropicbefore optimization134K5 MCP servers, 58 toolsAnthropic's example~55KGitHub MCP, 101 toolsold default64.6KGitHub MCP, 52 toolsnew default30.3K−53%

Figure 3. Context spent on tool definitions before the user types. Sources: GitHub, Anthropic.

  1. Write the contract: names, descriptions and schemas

The model reads your tool definition literally. Anything a developer would carry in their head has to be written into the definition.

Here’s what that looks like for one tool:

{ "name": "crm_search_customers", "description": "Find customers by name, email or company. Use this before any action on a customer. Do not use it to list all customers. Returns up to limit matches, most recently active first.", "inputSchema": { "type": "object", "properties": { "query": { "type": "string", "description": "Name, email address or company name. Partial matches allowed." }, "status": { "type": "string", "enum": ["active", "trial", "churned"], "description": "Optional. Filter by account status." }, "response_format": { "type": "string", "enum": ["concise", "detailed"], "description": "concise: name, plan and customer_ref only. detailed: adds recent orders and notes." }, "limit": { "type": "integer", "minimum": 1, "maximum": 20 } }, "required": ["query"], "additionalProperties": false } }

  1. Design the response: return signal, not dumps

Whatever a tool returns goes straight into the model’s context, and an agent’s context fills up fast.

A model can recover from an error only if the error tells it how. The MCP spec separates two kinds of errors. Protocol errors, such as calling a tool that doesn’t exist, are mainly for the client. Tool execution errors come back with isError: true and “contain actionable feedback that language models can use to self-correct,” so clients should pass them to the model.

OPAQUE ERRORModelToolbook_flight(date: 2026-11-01)ACTIONABLE ERRORModelToolbook_flight(date: 2026-11-01)Error 400nothing to changeInvalid departure date: mustbe in the future. Current dateis 2026-11-13. Pass dates asYYYY-MM-DD.book_flight(date: 2026-11-20)

Figure 4. The same failed call with two different error messages, and what the model can do next.

The first gives the model nothing to fix. The second tells it exactly what to change.

Connect a few MCP servers and you’ll pass 20 tools quickly. There are three ways to stop loading every definition up front, and each moves the cost somewhere else.

1 · TOOLSETS2 · TOOL SEARCH3 · CODE EXECUTIONMODEL CONTEXTreposissuespull_requestsNOT ENABLEDactionsprojectsdependabot53% fewer tokensGitHub default toolsetsMODEL CONTEXTtool_searchjira_searchjira_commentTool catalogall definitions1search2load~85% less contextAnthropic's exampleMODEL CONTEXTrun_codeSandboxno networkMCP serversscriptresult onlybindings150K → 2K tokensAnthropic's example

Figure 5. What sits in the model’s context under each pattern. Tool names are illustrative. Sources: GitHub; Anthropic on tool search and code execution.

Toolsets. Group tools and enable only the groups a task needs. GitHub’s default toolsets follow this pattern, and Google recommends choosing tools dynamically based on the conversation when you have many. It’s the simplest option, and it works when you can predict what a task needs.

Tool search. Give the model a tool for finding other tools. Anthropic’s Tool Search Tool cut context use by about 85% in its example, and raised Claude Opus 4’s accuracy on its MCP evaluations from 49% to 74%. Anthropic suggests it once your definitions pass about 10K tokens or you have more than 10 tools. OpenAI now supports deferring tools through tool search as well, on gpt-5.4 and later.

Code execution. Present tools as a typed code API and let the model write the code that connects them. Cloudflare’s Code Mode argues that “LLMs are better at writing code to call MCP, than at calling MCP directly.” Its reasoning is that models have seen far more real TypeScript than examples of tool calls. Anthropic describes the same idea in code execution with MCP, where a Google Drive-to-Salesforce workflow dropped from about 150,000 tokens to 2,000, because the intermediate data never passed through the model. Anthropic’s Programmatic Tool Calling cut average token use by 37% on complex research tasks.

The cost is real. Anthropic says running agent-generated code requires “a secure execution environment with appropriate sandboxing,” plus resource limits and monitoring. Cloudflare’s sandboxes have no internet access, and the code reaches tools only through bindings that hold the credentials. If you can’t operate a sandbox like that, use toolsets or tool search.

20+ toolsCan you predict thetools a task needs?Chained calls orlarge data, and asandbox you can run?yesnoyesnoToolsetsload only those groupsCode executiononly results reach the modelTool searchload definitions on demand

Figure 6. Choosing a pattern once you pass about 20 tools.

  1. When a tool should be an agent

Sometimes a tool’s job grows big enough to need its own prompt, tools and context. That’s when teams reach for multiple agents. There are two common shapes, and they behave differently.

AGENTS AS TOOLS · MANAGERUserManageragentresearch_agentbilling_agentHANDOFF · DECENTRALIZEDUserTriageagentBillingagent12handoff3callresult1 before · 2 handoff · 3 after

Figure 7. The manager keeps the conversation; with a handoff, the specialist takes it over. Patterns from OpenAI’s guide and Agents SDK.

OpenAI’s agent guide recommends getting the most out of a single agent first. When you do split, the Agents SDK docs distinguish agents as tools, where a manager keeps control, from handoffs, where another agent takes over the conversation. If one agent should own the conversation and combine the results, use agents as tools. Use handoffs when the specialist should talk to the user directly.

Anthropic’s research system shows both the benefit and the bill. Its multi-agent setup outperformed a single Claude Opus 4 agent by 90.2% on an internal research evaluation, but multi-agent systems used about 15 times as many tokens as a chat. Anthropic says the approach fits poorly when agents need the same context or depend heavily on each other, which includes most coding tasks. Those numbers come from Anthropic’s system, not yours, but the lesson carries over: split for parallel, independent work, not for tidiness.

0×5×10×15×Chat1×Single agent4×Multi-agent15×

Figure 8. Token use compared with a chat, in Anthropic’s research system. Specific to that system.

  1. Tools are where the damage happens

Almost every risk an agent poses runs through a tool. An agent can only read, write, spend or leak what its tools allow. That makes tool design a security and reliability problem, not just a prompting problem.

Simon Willison’s lethal trifecta is the clearest way to think about this. An agent that has access to private data, is exposed to untrusted content and has a way to send data out can be tricked into leaking that data. Models follow instructions wherever they appear, and they can’t reliably tell yours from an attacker’s.

This has already happened. In May 2025, Invariant Labs showed that a malicious issue in a public GitHub repository could make an agent using the GitHub MCP server read the user’s private repositories and publish their contents in a public pull request. Invariant stressed that this wasn’t a bug in the server’s code but a problem with how agents handle untrusted input. In trifecta terms, one agent held all three capabilities at once.

Private dataprivate reposUntrusted contentmalicious issueA way to send data outpublic pull requestleak

Figure 9. The lethal trifecta, with the GitHub MCP attack mapped onto it. Concept from Simon Willison.

The fix is in how you combine tools, not in a better prompt. Don’t give one agent all three. If it reads untrusted content, limit what it can do afterwards.

OpenAI recommends rating each tool as low, medium or high risk, based on read versus write access, reversibility, required permissions and financial impact, and then pausing or es

正文由 探How 从来源站点 RSS 同步,内容未经改写;遇到排版缺失或需要图片、视频时请以原文为准。

打开原文
去社区讨论 →