Docs/SDK/Tool Registry

Tool Registry

Expose typed, auditable tools to your agent (structured inputs/outputs + traceable execution), so tool calls are deterministic and debuggable.

This guide covers:

Registering tools with schemas (Pydantic in Python, Zod in TypeScript)
Generating LLM-ready tool specs
Executing tools with validation + tool_call trace events
Default tool packs (snapshot/click/type/scroll/evaluate-js/permissions)

Tool calls should be validated and replayable.

The Tool Registry gives tools the same failure semantics as the rest of the runtime: strict schemas, explicit capability checks, and trace events for post-mortems.

Why Tool Registry
Default tools
Register a typed tool
Execute tools (with tracing)
Capability checks

Why Tool Registry

Without typed tools, agents “call tools” with ambiguous payloads:

wrong field names
wrong types (string vs number)
missing required inputs

Tool Registry addresses this by:

validating inputs/outputs
producing JSON Schema / parameter specs for LLMs
emitting tool_call trace events (success/failure + duration)

Default tools

You can register a ready-made tool pack for common browser operations.

Tool	Purpose
`snapshot_state`	Capture a bounded snapshot state.
`click`, `type`, `press`	Core interaction primitives.
`scroll`, `scroll_to_element`, `click_rect`	Viewport movement + coordinate click.
`evaluate_js`	Bounded JavaScript evaluation.
`grant_permissions`, `clear_permissions`, `set_geolocation`	Permission management tools (backend-dependent).

Register a typed tool

from pydantic import BaseModel
from predicate.tools import ToolRegistry, ToolSpec

class EchoIn(BaseModel):
    message: str

class EchoOut(BaseModel):
    echoed:

Execute tools (with tracing)

When you execute tools through the registry, inputs/outputs are validated and tool_call events are emitted (if tracing is enabled).

from predicate.tools import ToolRegistry, ToolContext, register_default_tools

registry = ToolRegistry()
register_default_tools(registry, runtime)

ctx = ToolContext(runtime)
result = await registry.execute(

Capability checks

Some tools require backend capabilities (e.g., permissions). Keep failures explicit:

fail early with a structured “unsupported capability” error
handle it as a recovery path (switch strategy, escalate, or skip)

Filesystem tools — sandboxed file I/O tools
Permissions — permission tools (grant/clear/set geolocation)
Tracing — tool-call events in traces

Downloads

Filesystem Tools