OptionalannotationsAdvisory labels describing what this tool does — {readOnly?, destructive?, idempotent?}. Never enforced: they are handed to the onToolCall hook, which is where a script's policy over its own tools lives. Absent members mean the author did not say.
OptionaldescriptionFree-text description of when and how the model should use this tool.
JS function invoked when the model calls this tool. Receives the parsed arguments object as its single parameter; the return value is stringified (or JSON-encoded) and threaded back to the model as the tool result. If the function throws, the error is reported to the model so it can recover. A long result is clipped before it reaches the model, and the clip appends a line naming what was withheld — return a summary rather than a whole document if you want to choose what survives.
Optionalinput_JSON Schema describing the arguments the model will pass to the executor. Typically { type: "object", properties: {...}, required: [...] }. Optional — when omitted/null the tool is treated as taking no arguments. May be a JS object literal (Polyglot Value) or a Java Map/List tree depending on how the tool was constructed; use B.ai.tool.getInputSchema(tool) for a JS-friendly view. Typed as JSONSchema so an AiTool value is structurally a AiToolLiteral<JSONSchema> and can flow into B.ai.call's typed tools array.
Tool name. Must be unique within a single B.ai.call invocation. Required at execution time — tools whose name is null/blank are skipped with a warning.
A tool declaration plus its JS executor, exposed to the AI model in B.ai.call.
Example: ```javascript // A tool is a plain object; B.ai.tool.custom() is the typed way to build one. const tool = { name: "resident_allergies", description: "Lists a resident's known allergies", input_schema: { type: "object", properties: { id: { type: "string" } }, required: ["id"] }, annotations: { readOnly: true }, executor: (args) => allergiesFor(args.id).join(", "), }; B.ai.call({ message: B.net.request.parameter("q"), tools: [tool] }); ```