Tools

A tool is a directly registered operation invoked by name and arguments. Its descriptor specifies required authority and whether confirmation is needed. Execution can be synchronous; use a delegation when the product needs a separately tracked task lifetime.

Register a concrete operation

// Interface excerpt from package rmc, not a standalone program.
type ToolHandler interface {
    Descriptor() ToolDescriptor
    Invoke(context.Context, json.RawMessage) (json.RawMessage, error)
}

The descriptor includes the tool name, input schema, read/write effect, required action, and confirmation requirement. The handler owns the operation and its argument validation. Read the Northwind capability implementations for concrete tools and the registry for registration.

Invoke through room authority

room.invokeTool(toolName, argumentsValue, confirmationId?) calls the registered operation and returns its JSON result. The runtime checks the descriptor's required action against the tool name. Publishing an event named after a tool does not invoke it.

For a tool requiring confirmation, show the proposed action and exact arguments in your application. After the user approves, use room.confirmTool(toolName, argumentsValue) to obtain the confirmation ID, then pass it with those same arguments to invokeTool().

The runtime checks and consumes a confirmation bound to the room, tool, and argument hash. Obtaining it requires tool:confirm on the tool name. Confirmation is a separate condition from invocation authority. The SDK helper is not a user-consent UI; the product owns that interaction.

Handle results and uncertain execution

The invocation response is the direct result. The runtime also attempts internal tool trace publications, including tool.completed. Those traces are internal-visible and their publication is separate from the tool's external effect. Do not treat a trace as an atomic receipt for an external transaction.

If the response is lost, determine whether the destination performed the operation before blindly retrying a write. Reusing a consumed confirmation is not a general idempotency strategy. Any duplicate-safe external effect must be implemented at the destination or by the concrete integration.

Read ToolDescriptor and ToolHandler, runtime invocation and confirmation, and HTTP tool handlers. Compare room agents for event reactions and delegations for explicit background work.