Tools

Tool specification and decorator. define_tool(...) is callable, so the returned ToolSpec can be used as a decorator to attach a Python handler.

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	required
approval	dict	<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