> For the complete documentation index, see [llms.txt](/llms.txt). Every page on this site is also available as markdown at `.md`. # Tools Tool specification and decorator. `define_tool(...)` is callable, so the returned [`ToolSpec`](#flowai_harness.tools.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 ``"_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] = , 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