DefineToolOptions

defineTool 的声明形态(parameters 与 schema 二选一;都缺 = 无参数工具)

类型参数

Args

Args = Record<string, unknown>

属性

description

description: string;

模型可见说明(何时调用、做什么;双受众同一份)

effects?

optional effects?: readonly ("irreversible" | "financial" | "external" | "affects-others")[];

效应声明(应用协议 v1):irreversible(不可逆)/ financial(资金流动)/ external(触达外部系统或第三方)/ affects-others (影响其他用户或租户)。信号不是闸门——只进裁决人语境与遥测,不改任何确定性判定;词表外值声明期 fail-fast。缺省未声明。

guide?

optional guide?: string;

长文使用指南(装配期聚合注入 system 段;非模型 schema 面)

handler

handler: (args, ctx) => unknown;

业务实现:args 已过 schema 校验;返回任意可序列化值或字符串

参数

args

Args

ctx

ToolContext

unknown

name

name: string;

工具名(进模型 prompt 与权限规则;非空、无空白)

parameters?

optional parameters?: Record<string, ToolParameterSpec>;

JSON 参数表档:key → 参数声明

readOnly?

optional readOnly?: boolean;

只读声明(true = 可并发、plan 模式放行);缺省 false(保守按写工具对待)

schema?

optional schema?: ZodType<Args, any, Args>;

zod 直给档(高级;与 parameters 互斥)