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

Python
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_decorator

ToolNode

A unified registry and executor for callable tools from multiple sources (local functions, MCP servers).

Constructor

Python
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.

Python
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

tool_node_example.py
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

Python
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

Python
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

Python
@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

Python
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

Python
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

Python
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

Python
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

Python
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))  # False

UnsupportedToolParameterError

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

Python
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:

Python
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.

Python
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.


For task-focused guidance on using tools, see:

Last updated for v1.0.0Edit this page on GitHubReport an issue