设计LLMs能够理解的MCP工具架构
我在过去几个月里一直在构建MCP服务器，发现为AI代理设计工具架构与为人类设计REST API有着惊人的不同。
以下是一些在生产中有效和无效的模式：
**无效的模式：**
1. 细粒度的CRUD端点。我最开始使用了显而易见的端点，如get_request、update_request_status、update_request_assignee、add_comment等。代理经常会调用错误的端点或以错误的顺序链式调用。过多相似的工具导致了混淆。
2. 泛化的参数名称。一个名为“id”的字段在没有上下文的情况下对代理毫无意义。它会产生虚假的ID或传递错误实体的ID。
3. 稀疏的错误信息。返回“404 Not Found”并没有给代理提供任何有用的信息。它会无限期地重试同样的错误调用。
**有效的模式：**
1. 更少、更宽泛的工具。与其使用8个CRUD端点，不如将它们合并为3个：search_requests、get_request_detail、update_request。使用更小的工具集，代理犯错的次数大大减少。
2. 带有示例的描述性架构。在JSON架构中添加“description”字段及示例值显著提高了准确性。架构本身就是提示。
3. 丰富的错误响应。与其返回“404”，不如返回“未找到ID为‘abc’的请求。您是否想先进行搜索？可用工具：search_requests”，这实际上促使代理自我纠正。
4. 读-写模式。在结构化工具时，让代理在进行更改之前自然地获取上下文，显著减少了破坏性错误。
5. 危险操作的确认字段。为删除或批量更新添加一个必需的“confirm: true”参数，起到了减速带的作用，使代理三思而后行。
**思维模型的转变：** 你不是在为阅读文档的开发者设计API，而是在为一个只看到架构和最后几条消息的推理引擎设计接口。每个字段名称、描述和错误信息都是一个提示。
我很好奇其他构建MCP服务器的人是否发现了类似的模式或不同的方法。
查看原文
I've been building MCP servers for the past few months and found that
designing tool schemas for AI agents is surprisingly different from
designing REST APIs for humans.<p>Here are some patterns that worked and didn't work in production:<p>What didn't work:<p>1. Fine-grained CRUD endpoints. I started with the obvious
get_request, update_request_status, update_request_assignee,
add_comment, etc. The agent would frequently call the wrong one
or chain them in the wrong order. Too many similar tools = confusion.<p>2. Generic parameter names. A field called "id" meant nothing to the
agent without context. It would hallucinate IDs or pass the wrong
entity's ID.<p>3. Sparse error messages. Returning "404 Not Found" gave the agent
nothing to work with. It would retry the same bad call indefinitely.<p>What worked:<p>1. Fewer, wider tools. Instead of 8 CRUD endpoints, I collapsed them
into 3: search_requests, get_request_detail, update_request. The
agent made far fewer mistakes with a smaller tool set.<p>2. Descriptive schemas with examples. Adding "description" fields
with example values in the JSON schema dramatically improved
accuracy. The schema IS the prompt.<p>3. Rich error responses. Instead of "404", returning
"No request found with ID 'abc'. Did you mean to search first?
Available tool: search_requests" actually got the agent to
self-correct.<p>4. Read-before-write pattern. Structuring tools so the agent
naturally fetches context before making changes reduced
destructive mistakes significantly.<p>5. Confirmation fields for dangerous operations. Adding a required
"confirm: true" parameter for deletes/bulk updates acts as a
speed bump that makes the agent think twice.<p>The mental model shift: you're not designing an API for a developer
reading docs. You're designing an interface for a reasoning engine
that only sees the schema and the last few messages. Every field
name, description, and error message is a prompt.<p>Curious if others building MCP servers have found similar patterns
or discovered different approaches.