工具接口设计：从业务需求到参数 Schema

设计流程：先写"使用场景卡"

动手写代码前，先回答四个问题：

1. 模型什么时候会需要它？（触发时机 → 描述）
2. 需要哪些输入？哪些必填、哪些可默认？
3. 返回什么内容才能支撑下一步推理？
4. 出错时模型需要什么信息来自我修正？

参数设计清单

• 类型从简：string / number / boolean / enum 优先；嵌套对象能免则免；
• 枚举限定：固定选项用 enum（如 status: "open" | "closed"），杜绝自由发挥；
• 默认值兜底：可选项给默认值（page=1, limit=10）；
• 每个参数写 description：说明格式与含义（"YYYY-MM-DD 格式的开始日期"）；
• ID vs 名称：优先让模型传名称，由工具内部解析 ID——模型记不住内部主键。

返回值设计

• 结构化（JSON）+ 简短摘要字段，避免返回整页原始数据；
• 列表返回带总数与分页信息（"共 47 条，显示前 10 条"），提示模型可以翻页；
• 关键结果放前面：模型注意力对开头更敏感。

@tool
def search_orders(status: str = "all", page: int = 1) -> str:
    """按状态搜索用户的订单列表。
    status: 订单状态，可选 open(进行中)/shipped(已发货)/completed(已完成)/all
    page: 页码，从 1 开始，每页返回 10 条
    """
    ...

自查法：把工具交给一个"只读说明书的新同事"——他能否不看实现就正确调用？能，说明书就合格了。