Attach advisory labels describing what this tool does. They are never
enforced — they are handed to the onToolCall hook, so a script can hold
one policy over every tool it registers instead of a list of names.
const tool = B.ai.tool.custom()
.setName("archive_note")
.setDescription("Archives a nursing note")
.setAnnotations({ destructive: true, idempotent: true })
.setSchema({type: "object", properties: {id: {type: "string"}}, required: ["id"]})
.setExecutor((args) => archive(args.id));
// …then, on the call:
onToolCall: (c) => c.annotations && c.annotations.destructive
? { action: "defer" }
: { action: "run" },
Advisory labels: {readOnly?, destructive?, idempotent?}. Omitted members mean the author did not say.
Set the free-text description shown to the model. Returns this builder for chaining.
When and how the model should use this tool.
Finalize the custom tool by setting the executor. When a schema was
captured via setSchema(...), args is typed via FromSchema<S> —
typos in field names and wrong-shape access fail at compile time. When
no schema was captured (S = never), the executor must be zero-arg
since the model has no input_schema to send. Returns the underlying
AiTool.
const tool = B.ai.tool.custom()
.setName("add_1")
.setDescription("adds one!")
.setSchema({
type: "object",
properties: {
a: { type: "integer" },
b: { type: "integer" },
},
required: ["a", "b"],
})
.setExecutor((args) => args.a + args.b + 1);
Executor function. Zero-arg when no schema is set; otherwise args is typed against the schema captured by setSchema(...).
Set the tool name. Returns this builder for chaining.
Tool name. Must be unique within a single B.ai.call invocation.
Set the JSON Schema describing the tool's input arguments. Captures the
schema's literal type into the returned builder so the subsequent
.setExecutor(...) call can type its args parameter via
FromSchema<S>. The const modifier on the generic narrows literal
types automatically — as const is only needed on nested arrays
(e.g. enum) to preserve their literal members.
const tool = B.ai.tool.custom()
.setName("add_1")
.setDescription("adds one!")
.setSchema({
type: "object",
properties: {
a: { type: "integer" },
b: { type: "integer" },
},
required: ["a", "b"],
})
.setExecutor((args) => args.a + args.b + 1);
The JSON Schema literal describing the tool's argument shape. Sent verbatim to the model as the tool's input_schema.
Fluent builder for B.ai.tool.custom(). The type parameter S is the literal type of the schema captured by setSchema(); defaults to
never, which forces setExecutor() to require a zero-arg function. After setSchema(...) narrows S, setExecutor()'sargsparameter is typed via FromSchema.Example: ```javascript const tool = B.ai.tool.custom() .setName("add_1") .setDescription("adds one!") .setSchema({ type: "object", properties: { a: { type: "integer" }, b: { type: "integer" } }, required: ["a", "b"], }) .setExecutor((args) => args.a + args.b + 1); // args is typed from the schema ```