Tools
In shortToolNode, ToolResult, and utilities for tool registration and execution.
- 11 min read
- 10 sections
- Updated
- v1.0.0
- Markdown
ToolNode is a unified registry and executor for Python functions and MCP tools. It automatically generates JSON schemas from type annotations, executes tool calls in parallel, handles errors, and publishes events. Pair it with Agent to give LLMs access to callable tools, or use the utilities and decorators to define, inspect, and manage tool metadata.
Import paths
from tenxgraph.core.graph import ToolNode
from tenxgraph.core.state import ToolResult
from tenxgraph.core.graph.tool_node import UnsupportedToolParameterError, HAS_MCP, HAS_FASTMCP
from tenxgraph.core.graph.tool_node import MCPAuthContext, forward_credential
from tenxgraph.utils import tool, get_tool_metadata, has_tool_decoratorToolNode
A unified registry and executor for callable tools from multiple sources (local functions, MCP servers).
Constructor
ToolNode(
tools,
client=None,
pass_user_info_to_mcp=False,
max_result_chars=None,
mcp_include=None,
mcp_exclude=None,
mcp_prefix=None,
mcp_max_result_chars=None,
mcp_max_description_chars=None,
mcp_cache_tools=True,
mcp_connect_timeout=30.0,
mcp_auth=None,
)| Parameter | Type | Default | Description |
|---|---|---|---|
tools |
Iterable[Callable] |
required | Local Python functions to register. Each is registered under its __name__. Pass an empty list when only serving MCP tools. |
client |
fastmcp.Client | None |
None |
MCP client for remote tool access. Requires pip install "10xgraph[mcp]". |
pass_user_info_to_mcp |
bool |
False |
Send the caller to MCP tool calls as request metadata (meta["user"]), readable on the server as ctx.request_context.meta. It is unsigned: the server cannot verify it, so anything that can reach the MCP endpoint can claim any user. Use it only for a trusted internal server or where the identity is informational; for per-user or per-tenant access control use mcp_auth. It is not sent as a tool argument. It logs a warning if the client’s call_tool has no meta parameter. |
max_result_chars |
int | None |
None |
Cap on the text a local tool returns. Longer text is cut and a marker is appended, so one huge result is not saved to state and re-sent to the model every turn. None means no cap. |
mcp_include |
Iterable[str] | None |
None |
Allow-list of MCP tool names. Only these are shown to the model and callable. None means every tool the server lists. |
mcp_exclude |
Iterable[str] | None |
None |
MCP tool names to hide and refuse, applied after mcp_include. |
mcp_prefix |
str | None |
None |
String put in front of every MCP tool name the model sees (for example "github_"), so two ToolNodes can expose servers that share a tool name. It is removed again before the server call. mcp_include and mcp_exclude match the server’s own names, without the prefix. |
mcp_max_result_chars |
int | None |
None |
Cap on the text of one MCP tool result. Longer output is cut and a marker is appended. None means no cap. |
mcp_max_description_chars |
int | None |
None |
Cap on an MCP tool description, which is sent to the model on every call. A longer description is cut and ends in .... None means no cap. |
mcp_cache_tools |
bool |
True |
List the server’s tools once per ToolNode and reuse the list, which saves a connect and list round trip per model call. Set False to list the server every time. See MCP tool list caching. |
mcp_connect_timeout |
float | None |
30.0 |
Seconds to wait for the MCP connection to open. Only the connect is bounded, never a tool call. If the connect times out, the tool call fails like any other tool error (the model sees a generic failure and the log says MCP connect timed out after ...s), and a tool listing that times out returns no MCP tools and is not cached. None waits without a limit. |
mcp_auth |
Callable[[MCPAuthContext], Awaitable[dict[str, str]]] | None |
None |
Async function that returns HTTP headers for one MCP request, so each call carries its own credentials (for example a short-lived JWT naming the user and the agent as actor, which the server verifies). It runs before every tool listing and tool call, and its headers win over the transport’s auth= on the same name. Needs a client (ValueError otherwise), fastmcp 4.1.7 or later (ImportError otherwise) and an HTTP transport, streamable HTTP or SSE (ValueError for stdio or in-memory). The tool list is cached per node and shared by all users, so it must not differ per user. See MCPAuthContext. |
tools may also be a generator. If a different callable is registered under the name of an existing tool, ToolNode logs a warning and the new one replaces the old.
Argument coercion. Arguments the model sends are coerced against the tool’s type hints in lax mode. A value that converts cleanly is converted: "5" for an int becomes 5, and a number for a str becomes a string. Unknown extra keys are ignored. A value that cannot convert ("abc" for an int) is not run: the model gets a failed tool result and the tool does not execute.
Raises: TypeError when an item in tools is not callable; ImportError when a client is given but the MCP packages are not installed.
Methods
| Method | Signature | Returns | Description |
|---|---|---|---|
invoke |
await invoke(name: str, args: dict, tool_call_id: str, config: dict, state: AgentState) |
Message |
Execute a single tool call by name. Returns a Message with the result or error information (the signature also allows a dict). |
all_tools |
await all_tools(tags: set[str] | None = None, config: dict | None = None) |
list[dict] |
Async method returning JSON schemas for all registered tools, optionally filtered by tags. |
all_tools_sync |
all_tools_sync(tags: set[str] | None = None, config: dict | None = None) |
list[dict] |
Synchronous version of all_tools. |
add_tool |
add_tool(tool: Callable) |
None |
Register one more function after construction. Raises TypeError if it is not callable. |
refresh_mcp_tools |
await refresh_mcp_tools() |
list[dict] |
Drop the cached MCP tool list, fetch it from the server again and return the JSON schemas. Returns [] when there is no MCP client. |
MCP tool list caching
By default a ToolNode fetches the MCP server’s tool list once and reuses it for the life of the node. Tools that you add to the server later do not appear, and removed tools stay listed, until you refresh. A failed listing is never cached, so a server that was down at the first call is listed again on the next one.
tool_node = ToolNode([], client=client)
# After you deploy new tools to the MCP server:
schemas = await tool_node.refresh_mcp_tools()If your server changes its tools while the process runs and you want every model call to see the change, construct the node with mcp_cache_tools=False. That costs a connect and list round trip per model call.
MCPAuthContext
mcp_auth is an async callable (MCPAuthContext) -> dict[str, str]. It must return a dict of header names to string values, or the call fails with TypeError. MCPAuthContext is a frozen dataclass:
| Field | Type | Meaning |
|---|---|---|
identity |
Identity | None |
The caller from config["user"]. |
credential |
UserCredential | None |
The caller’s credential from config["credential"]. Its repr is redacted. |
tool_name |
str | None |
The server’s tool name, or None while the tool list is fetched. |
server |
str | None |
The server URL of the client’s transport, when known. |
thread_id |
str | None |
The run’s thread id. |
run_id |
str | None |
The run id. |
forward_credential is a ready-made mcp_auth that sends the caller’s own token as Authorization. Use it only for a server that accepts that same token. For a server that enforces per-user or per-tenant access, sign a short-lived token yourself, or exchange the user’s token, and return it from your own function. See Use MCP tools and Calling services as the user.
Example
from tenxgraph.core.graph import Agent, ToolNode
def lookup_order(order_id: str) -> dict:
"""Look up an order by ID."""
return {"order_id": order_id, "status": "shipped"}
def refund_order(order_id: str, amount: float) -> dict:
"""Refund an order."""
return {"refund_id": "R-1", "amount": amount}
# Register local functions; each is exposed under its __name__
tool_node = ToolNode([lookup_order, refund_order])
# Inspect the JSON schemas the model will see
schemas = tool_node.all_tools_sync()
print(len(schemas)) # 2
# Add another tool after construction
def cancel_order(order_id: str) -> dict:
"""Cancel an order."""
return {"order_id": order_id, "status": "cancelled"}
tool_node.add_tool(cancel_order)
# Give the tools to an agent; also add tool_node to your StateGraph as a node
agent = Agent(model="gpt-4o", provider="openai", tool_node=tool_node)To wire the agent, the tool node and the routing edges into a graph, see Define custom tools with @tool.
ToolResult
Return type for tool functions that need to update graph state and return a message to the AI.
Constructor
ToolResult(message=None, state=None, is_error=False, *, content=None)| Parameter | Type | Default | Description |
|---|---|---|---|
message |
Any |
None |
The text response to return to the AI. content is accepted as an alias. |
state |
dict[str, Any] | None |
None |
Dict mapping state field names to new values. Only fields present are updated. |
is_error |
bool |
False |
If True, marks the result as a failed tool call (status=“failed”). |
content |
Any |
None |
Alias for message; ignored if message is provided. |
Example
from tenxgraph.core.state import ToolResult, AgentState
class MyState(AgentState):
jd_name: str = ""
def update_context(state: MyState, jd_name: str) -> ToolResult:
return ToolResult(
message=f"JD name updated to '{jd_name}'",
state={"jd_name": jd_name},
)tool decorator
Mark a function as a tool with metadata for schema generation and filtering.
Signature
@tool(
_func=None,
*,
description: str | None = None,
tags: list[str] | set[str] | None = None,
provider: str | None = None,
capabilities: list[str] | None = None,
metadata: dict[str, Any] | None = None,
parameters: dict[str, Any] | None = None,
record_tool_result: bool = True,
)| Parameter | Type | Default | Description |
|---|---|---|---|
description |
str | None |
None |
Tool description. If None, uses the function’s docstring, or “No description provided.” when there is none. |
tags |
list[str] | set[str] | None |
None |
Tags for categorizing and filtering tools. Examples: ["search", "web"]. |
provider |
str | None |
None |
Provider or source of the tool (e.g., “local”, “mcp”, “composio”). |
capabilities |
list[str] | None |
None |
Capabilities or permissions required by the tool. Examples: ["read_files", "network_access"]. |
metadata |
dict[str, Any] | None |
None |
Additional arbitrary metadata for the tool. |
parameters |
dict[str, Any] | None |
None |
Explicit JSON Schema dict for parameters. Bypasses automatic schema generation. |
record_tool_result |
bool |
True |
Record this tool’s results in the checkpointer’s tool execution ledger so a replay or resume does not run it again. Set False for read-only tools (search, weather, lookups); they may then run twice after a crash or on resume. record_tool_result=False on the checkpointer turns recording off for every tool and wins over this flag. See Replay-safe tools. |
Returns: The decorated function with metadata attached as private attributes (_py_tool_*). The function behaves identically to the original.
Tool name. The function name is the tool name the model sees. There is no name argument: @tool(name=...) raises a TypeError. To change the name, rename the function. @tool works on bound methods too.
Raises: ValueError if the decorated object is not callable or if parameters is provided but not a dict.
Example
from tenxgraph.core.graph import ToolNode
from tenxgraph.utils import tool
@tool(tags=["search", "orders"])
def lookup_order(order_id: str) -> dict:
"""Look up an order by ID."""
return {"order_id": order_id, "status": "shipped"}
@tool(tags=["write", "payments"])
async def refund_order(order_id: str, amount: float) -> dict:
"""Refund an order."""
return {"refund_id": "R-1", "amount": amount}
tool_node = ToolNode([lookup_order, refund_order])get_tool_metadata
Extract all tool metadata from a decorated function.
Signature
get_tool_metadata(func: Callable) -> dict[str, Any]| Parameter | Type | Description |
|---|---|---|
func |
Callable |
A function that may have been decorated with @tool. |
Returns: Dict with keys: description, tags (set), provider, capabilities, metadata, parameters. Unset values are None; tags is an empty set when unset.
Example
from tenxgraph.utils import tool, get_tool_metadata
@tool(tags=["test"])
def example():
"""Example function."""
pass
metadata = get_tool_metadata(example)
print(metadata["tags"]) # {"test"}has_tool_decorator
Check if a function has been decorated with @tool.
Signature
has_tool_decorator(func: Callable) -> bool| Parameter | Type | Description |
|---|---|---|
func |
Callable |
The function to check. |
Returns: True if the function has been decorated with @tool, False otherwise.
Example
from tenxgraph.utils import tool, has_tool_decorator
@tool
def decorated():
pass
def not_decorated():
pass
print(has_tool_decorator(decorated)) # True
print(has_tool_decorator(not_decorated)) # FalseUnsupportedToolParameterError
Raised when a tool parameter annotation cannot be expressed as a portable JSON Schema.
Supported annotations are str, int, float, bool, common stdlib scalars (datetime, date, time, UUID, Path, Decimal, bytes), Optional, list, dict, Literal, Enum subclasses, pydantic models and dataclasses, and nestings of those. Anything else, including TypedDict, raises this error when schemas are built. Pass @tool(parameters=...) to supply a hand-written schema instead.
Subclasses TypeError so existing except TypeError handlers around tool registration continue to work.
Example
from tenxgraph.core.graph.tool_node import UnsupportedToolParameterError
from typing import TypedDict
from tenxgraph.core.graph import ToolNode
class Options(TypedDict):
verbose: bool
def bad_tool(options: Options) -> str:
"""A tool whose parameter (a TypedDict) is not supported."""
return "ok"
try:
# Schemas are built from annotations; unsupported ones raise this error
schemas = ToolNode([bad_tool]).all_tools_sync()
except UnsupportedToolParameterError as e:
print(f"Cannot register tool: {e}")HAS_MCP and HAS_FASTMCP
Boolean flags indicating whether the Model Context Protocol and FastMCP packages are installed.
Use these to conditionally enable MCP features without importing optional dependencies:
from tenxgraph.core.graph import ToolNode
from tenxgraph.core.graph.tool_node import HAS_MCP, HAS_FASTMCP
def my_function(text: str) -> str:
"""Echo text."""
return text
if HAS_FASTMCP and HAS_MCP:
from fastmcp import Client
client = Client("http://localhost:8000/mcp") # replace with your MCP server
tools = ToolNode([my_function], client=client)
else:
print('MCP support requires: pip install "10xgraph[mcp]"')
tools = ToolNode([my_function])Per-tool access control
Permissions guard API routes. Inside a tool you have the run config, the authenticated identity and the authorization helpers, so you decide what each tool may do. A tool receives these by naming the parameter, and they are not shown to the model:
tool_call_id, state, config, emit, generated_id, context_manager, publisher, checkpointer, store, task_manager.
from tenxgraph.core.authz import can, get_identity
from tenxgraph.core.state import ToolResult
from tenxgraph.utils import tool
@tool
def delete_record(record_id: str, config: dict) -> ToolResult | str:
"""Delete a record."""
if not can(config, "store:delete"):
return ToolResult(message="You do not have permission to delete records.", is_error=True)
identity = get_identity(config)
user_id = identity.user_id if identity else "anonymous"
return f"Record {record_id} deleted by {user_id}."Return a ToolResult with is_error=True to refuse in words the model can relay. A raised exception reaches the model only as a generic failure with a reference. See Control access inside a tool for the full guide, including the no-auth case.
Related guides
For task-focused guidance on using tools, see: