Tools

The @tool decorator and tool primitives. For the conceptual model and the LLM-tool-loop interaction see concepts/behaviors and the Writing tools guide.

Decorator + base

Register a function as a Tool.

The decorated function's signature is (args: input_schema, ctx: ToolContext) -> output_schema. The runtime validates args against input_schema before invocation and validates the return value against output_schema after.

Keyword-only on purpose — too many fields for safe positional binding.

to_definition()

Provider-facing tool definition.

Sent in the tools= parameter to LLMProvider.complete(). Anthropic and OpenAI both accept a similar shape; the provider translates if needed.

Registry helpers

Return a copy of the global @tool registry, in registration order.

This is the list a new Runtime snapshots when tools=[...] is not passed. It is a copy: mutating the returned list neither registers nor unregisters anything — use the @tool decorator to add and :func:clear_tool_registry to reset.

Empty the global @tool registry. Test-isolation helper.

Decoration pushes into a module-level list that persists for the life of the process, so tests that register tools clear it between cases (mirroring the @behavior registry's isolation pattern). Runtimes constructed before the clear keep working — the registry is snapshotted at runtime construction, not read per-dispatch.