项目的工具调用如何设计？

工具调用需要把模型选择能力、应用执行动作、结果回传三件事接起来。项目中先按业务操作封装工具，给出清楚的名称、用途和参数Schema；模型生成工具名、调用ID与参数后，执行器校验并调用业务函数，再把结果关联到原调用回传，让Agent继续决策或回答。

以研搜Agent为项目示例，搜索、查数据库、读附件和生成报告分别是不同能力。工具层负责实际访问与错误处理，Agent负责决定何时使用和如何组合。实现重点是让每一步有清楚契约，而不是把所有业务入口都暴露成万能函数。

名称用动作加对象，例如“搜索订单日志”，描述写清能查什么、适用时间范围、返回哪些字段及与相似工具的区别。参数尽量贴近任务语义，使用枚举、范围和必要字段，身份与租户由认证上下文注入。

工具粒度要兼顾可组合性和调用成本。返回整库日志让模型自己筛选会浪费上下文；可以提供筛选、分页、字段投影和产物引用。但把查询、修改、通知全塞进一个不透明工具，又会让副作用和重试边界难以控制。

执行器从注册表解析工具，校验参数结构与业务条件，再检查访问范围。格式正确不代表订单存在或属于当前用户。依赖前一步返回值的调用串行；相互独立且不争用资源的查询可以并行，并设置并发上限。

调用结果应区分成功、无数据、参数错误、权限不足、可重试故障和结果未知，返回必要数据、时间及来源。网络抖动可以有限重试；写操作还要结合幂等键与回执查询，防止超时后重复提交。把执行器产生的真实结果回传，不能让模型自己补出“执行成功”。

准备正常请求、相似工具混淆、参数缺失、分页、超时和重复提交等案例，分别看工具选择、参数正确、最终任务完成、调用次数、耗时及Token成本。失败时检查完整调用轨迹，区分选错工具、参数不对、执行失败和总结错结果。

工具描述放在哪里？ 优先用模型接口提供的结构化工具定义；Skill或系统说明可以补工作方法，但不必复制全部Schema。具体消息格式随模型接口而变，应用适配层负责转换。

国内：JavaGuide：结构化输出与Function Calling：采用格式与契约的区分，说明正文中参数可解析为何不等于业务可执行。
国内：zero2Agent：工具管理：依据工具管理中的参数校验、依赖调度与失败分类，说明正文中工具执行层的职责。
国内：WeThinkIn：函数调用与协议边界：依据函数调用交互过程，说明正文中模型提出调用、应用执行与结果关联的分工。
国外：Anthropic：Writing effective tools for agents：借鉴工具粒度、命名空间与评估案例，说明正文中如何改善模型选择和调用效率。
国外：Anthropic：Building effective agents：依据工具接口设计，说明正文中描述、边界和参数形式为何影响调用质量。