Tools

Tools are explicit model-callable capabilities attached to agents. They define what an agent may call, what input shape the runtime validates, what output shape is documented, and whether the call needs approval.

Use custom tools for application-specific work such as lookups, search, read-only analysis, previews, or reference creation. Runtime-owned built-in toolkits expose capabilities such as agent routing, plan storage, references, catalog search, and SQL execution.

define_tool(...) creates a ToolSpec. It is callable, so the returned spec can also be used as a decorator to attach a Python handler.

Tool input and output schemas are normalized by normalize_schema(...), which accepts JSON Schema dictionaries, Pydantic models, simple type maps, and other Pydantic-exportable type hints.

For the full tool model, approval guidance, and built-in toolkit list, see the Tools concept.

define_tool

define_tool(name: 'str', input_schema: 'Any', description: 'str' = '', approval: 'str | Mapping[str, Any] | Callable[..., bool]' = 'never', output_schema: 'Any | None' = None, binding_id: 'str | None' = None) -> 'ToolSpec'

Parameter	Type	Default
name	str	required
input_schema	Any	required
description	str	''
approval	str | Mapping[str, Any] | Callable[..., bool]	'never'
output_schema	Any | None	None
binding_id	str | None	None

Returns: ToolSpec

Create a validated Flow AI tool spec.

The returned value is callable, so it can be used as a decorator:

@define_tool(name="search", input_schema={"query": str}).

Args: name: Tool name presented to the model. input_schema: Tool input schema: a JSON Schema mapping, a Pydantic model class, a simple type map such as {"query": str}, or any type hint Pydantic can export. description: Tool description presented to the model. approval: Approval policy: "never" (default), "always", a mapping {"kind": "dynamic", "value": predicate_id}, or a callable predicate. A callable becomes a dynamic policy whose id is binding_id or "<name>_approval", with the callable attached as the approval handler. output_schema: Optional output schema, normalized like input_schema. binding_id: Stable binding key for handler registration; defaults to the tool name.

Returns: A frozen ToolSpec. Bind a Python handler with .bind(handler) or by calling the spec as a decorator.

Raises: ValueError: If approval is not a recognized policy, or a callable approval is supplied without a tool name. TypeError: If a schema input cannot be normalized to JSON Schema.

ToolSpec

ToolSpec(*, name: str, description: str = '', inputSchema: dict[str, typing.Any], approval: dict[str, typing.Any] = <factory>, outputSchema: dict[str, typing.Any] | None = None, bindingId: str | None = None, handler: collections.abc.Callable[..., typing.Any] | None = None, approvalHandler: collections.abc.Callable[..., bool] | None = None) -> None

Parameter	Type	Default
name	str	required
description	str	''
inputSchema	dict[str, Any]	required
approval	dict[str, Any]	<factory>
outputSchema	dict[str, Any] | None	None
bindingId	str | None	None
handler	collections.abc.Callable[..., Any] | None	None
approvalHandler	collections.abc.Callable[..., bool] | None	None

Returns: None

Language-neutral tool specification plus optional Python binding.

bind

bind(self, handler: 'Callable[..., Any]') -> 'ToolSpec'

Parameter	Type	Default
handler	Callable[..., Any]	required

Returns: ToolSpec

Return a copy of this spec with a Python handler attached.

__call__

__call__(self, handler: 'Callable[..., Any]') -> 'ToolSpec'

Parameter	Type	Default
handler	Callable[..., Any]	required

Returns: ToolSpec