.tool()

Signature

agent.tool(config: ToolConfig): XsafAgent

.tool() registers one model-visible tool. Tool names must use lowercase snake_case and must not collide with another tool, delegate, or discovered MCP tool.

Usage

agent.tool({
  name: "lookup_order",
  description: "Look up an order by ID",
  input: orderInputSchema,
  async execute(input, context) {
    return orders.get(input.orderId);
  },
  timeout: 5_000,
  retries: 1,
  approval: "human",
});

The input contract implements both Standard Schema V1 validation and Standard JSON Schema V1 publication. XSAF validates input before approval or execution.

Executable tools require an explicit .sandbox(). Set approval: "human" for sensitive operations and register the policy with .approve().

Tool execution, retries, cancellation, timeouts, approval, sandboxing, and events all pass through one centralized pipeline. See Tools & Security for schema examples and the complete security model.