tool()

Register a function as a Talk Box tool.

Usage

Source

tool(
    _func=None,
    *,
    name=None,
    description=None,
    category=ToolCategory.CUSTOM,
    examples=None,
    requires_confirmation=False,
    timeout_seconds=None,
    max_retries=0,
    tags=None,
    registry=None
)

Use @tool as a decorator on any function to make it available to ChatBot conversations and the ToolRegistry. The decorator supports two forms: bare (@tb.tool) and with keyword arguments (@tb.tool(description="...")).

Parameters

_func: Optional[F] = None

Internal parameter that captures the decorated function when the decorator is used without parentheses. Do not pass this explicitly.

name: Optional[str] = None

Display name for the tool. Defaults to the function name.

description: Optional[str] = None

Human-readable description shown to the LLM when it decides which tool to call. Defaults to the function’s docstring.

category: ToolCategory = ToolCategory.CUSTOM


A ToolCategory value used for filtering and dashboard display. Defaults to ToolCategory.CUSTOM.

examples: Optional[List[str]] = None

Optional list of example invocation strings for documentation.

requires_confirmation: bool = False

If True, the tool will ask the user for confirmation before executing. Defaults to False.

timeout_seconds: Optional[float] = None

Maximum wall-clock time (in seconds) before the tool execution is cancelled. None means no limit.

max_retries: int = 0

Number of automatic retries on failure. Defaults to 0.

tags: Optional[List[str]] = None

Freeform string tags for discovery and filtering.

registry: Optional[ToolRegistry] = None

A ToolRegistry to register the tool in. Defaults to the global registry returned by get_global_registry().

Returns

Callable

The original function, with a _talk_box_tool attribute attached.

Examples

Register a tool with keyword arguments:

import talk_box as tb

@tb.tool(description="Add two numbers", category=tb.ToolCategory.DATA)
def add(x: int, y: int) -> int:
    return x + y

Register a tool without arguments (bare decorator):

@tb.tool
def greet(name: str) -> str:
    return f"Hello, {name}!"

See Also

ToolCategory, ToolContext, ToolResult, get_global_registry()