任务级 agent API 会说明一项操作能完成什么、何时应该使用、何时不应使用，以及可能产生哪些影响。端点结构本身只能说明如何发送请求。模型选择工具时，两类信息都需要。
“语义化”听起来也许比实际工作宏大。真正需要的改动很简单：围绕用户任务设计工具，而不是围绕数据库表和内部服务边界设计。
有效的端点仍可能含义不清
以下面的 REST 操作为例：
POST /users/{id}/status
{"value":"inactive"}
方法、路径、请求体和响应都可以拥有完整文档，但契约仍未说明 inactive 会暂停登录、停止计费、移除任务、安排删除，还是只更改 CRM 标签。
开发者可以阅读周边文档，一次性解决这种歧义。模型却可能在每次运行时重新面对多个相似工具。
将意图写入可调用契约
较弱的工具：
set_user_status
Set a user's status.
任务级工具：
suspend_workspace_member
Temporarily block one member from signing in to this workspace.
Use when an administrator asks to suspend access without deleting the account.
Do not use for billing cancellation, workspace deletion, or permanent data removal.
第二段描述向模型说明了任务、权限、影响和排除场景。其 schema 仍应标识工作区、成员、原因，以及必要时的审批 ID 或操作 ID。
MCP 工具规范为每项工具提供名称、描述、输入 schema、可选输出 schema 和 annotation，但不会代替你编写这些边界。
将一项任务映射到最精简且有用的结果
Agent 选择下一步操作时，通常不需要后端的完整响应。只返回用于决定下一步的字段。
例如，查询订单时可以返回：
{
"orderId": "1842",
"status": "shipped",
"estimatedDelivery": "2026-09-02",
"canCancel": false
}
不要返回内部数据库字段、提供商 token 或 200 KB payload，再要求模型重新从中寻找答案。REST 转 MCP 指南介绍了如何通过转换层将多项内部调用合并为一项任务结果。
明确说明副作用和失败行为
每项工具都应记录：
- 它会读取、写入、产生费用、发送内容还是删除内容；
- 对哪个调用方和资源执行授权；
- 是否需要审批；
- 操作能否安全重试；
- 哪些稳定的失败类型会改变下一步操作；
- 哪些结果字段具有权威性。
工具 annotation 可以帮助客户端展示风险，但客户端必须将来自不受信任服务器的 annotation 视为不可信信息。真正的限制应由策略和后端强制执行。
清晰区分相似工具
相互重叠的工具需要明确写出排除场景。如果服务器提供 search_customers、find_contacts 和 query_accounts，每项描述都应该说明自己负责哪类实体和任务。如果无法写出清晰区别，就合并工具或移除其中一个。
工具选择错误调试指南会先检查工具列表和调用追踪，再考虑修改系统提示词。
分别测试选择和执行
创建应该选择每项工具的提示词，以及不应选择任何工具的提示词。固定工具列表、描述、模型和设置，在实际执行前记录选择结果。
然后使用有效、无效、未授权和重复的输入测试执行。即使工具很容易被正确选中，调用时仍可能不安全。
先重写最相似的一对工具
找出描述中共享词汇最多的两个工具，为每项分别写明任务、使用条件、排除场景、副作用和下一步所需结果。如果边界仍然模糊，很可能是内部实现边界泄露到了 agent 接口中。
下方的提示词会执行这项歧义测试，并创建一组聚焦的评估用例。