Tools

Tool system for AI function calling. See the Tool Calling & Policies guide and MCP Tool Provider guide for usage examples.

ToolPolicy

Bases: BaseModel

Per-agent allow/deny rules for tool access.

Rules use :func:fnmatch.fnmatch glob patterns (e.g. "mcp_*", "search_*").

Resolution order:

1. Empty allow and empty deny → permit all (backward compatible).
2. If the tool name matches any deny pattern → blocked.
3. If allow is non-empty and the tool name matches no allow pattern → blocked.
4. Otherwise → permitted.

In short: deny always wins, and a non-empty allow list is a whitelist.

Role overrides ~~~~~~~~~~~~~~

role_overrides maps :class:~roomkit.models.enums.ParticipantRole string values (e.g. "observer", "member") to :class:RoleOverride instances.

Call :meth:resolve with a role to obtain an effective ToolPolicy that merges the base rules with the role-specific override.

resolve

resolve(role=None)

Return an effective ToolPolicy for the given role.

If role is None or has no override entry, returns self unchanged (backward compatible).

is_allowed

is_allowed(tool_name)

Return True if tool_name passes the policy.

as_filter

as_filter()

Return a callable (tool_name) -> bool suitable for :func:filter.

RoleOverride

Bases: BaseModel

Per-role tool policy override.

mode controls how the override combines with the base policy:

• "restrict" (default): deny lists are unioned, allow lists are intersected (a tool must pass both the base and override allow lists).
• "replace": the override completely replaces the base policy.

MCPToolProvider

MCPToolProvider(url, *, transport='streamable_http', tool_filter=None, headers=None)

Discover and invoke tools from an MCP server.

Supports both streamable_http (default) and sse transports.

Usage::

async with MCPToolProvider.from_url("http://localhost:8000/mcp") as mcp:
    tools = mcp.get_tools()          # list[AITool]
    handler = mcp.as_tool_handler()   # ToolHandler for AIChannel

tool_names property

tool_names

Return the names of all discovered tools.

from_url classmethod

from_url(url, *, transport='streamable_http', tool_filter=None, headers=None)

Create an MCPToolProvider for the given URL.

The provider is not connected until used as an async context manager.

Parameters:

Name	Type	Description	Default
url	str	MCP server URL.	required
transport	str	"streamable_http" (default) or "sse".	'streamable_http'
tool_filter	Callable[[str], bool] | None	Optional predicate to include only matching tool names.	None
headers	dict[str, str] | None	Optional HTTP headers sent with every request.	None

Returns:

Type	Description
MCPToolProvider	An MCPToolProvider instance (not yet connected).

get_tools

get_tools()

Return discovered tools as RoomKit AITool instances.

get_tools_as_dicts

get_tools_as_dicts()

Return discovered tools as plain dicts (for binding metadata).

call_tool async

call_tool(name, arguments, *, timeout=30.0)

Call a tool on the MCP server and return the result as a string.

Parameters:

Name	Type	Description	Default
name	str	Tool name.	required
arguments	dict[str, Any]	Tool arguments dict.	required
timeout	float	Maximum seconds to wait for a response.	30.0

Returns:

Type	Description
str	Result string. Single TextContent → plain text; multi-part → JSON array;
str	error results → {"error": "..."}.

as_tool_handler

as_tool_handler()

Return a ToolHandler suitable for AIChannel(tool_handler=...).

Unknown tools (not from this MCP server) return {"error": "Unknown tool: <name>"}, which allows composition via compose_tool_handlers.

compose_tool_handlers

compose_tool_handlers(*handlers)

Chain multiple ToolHandlers so the first one that handles a tool wins.

Each handler is tried in order. If a handler returns a JSON object with {"error": "Unknown tool: ..."} the next handler is tried. The last handler's result is always returned as-is (even if it's an unknown-tool error).

Parameters:

Name	Type	Description	Default
*handlers	ToolHandler	Two or more ToolHandler callables.	()

Returns:

Type	Description
ToolHandler	A single ToolHandler that dispatches to the first matching handler.

Raises:

Type	Description
ValueError	If fewer than two handlers are provided.