Tools API Reference¶

ToolRegistry¶

Central registry for all tools available to an agent.

`grampus.tools.registry.ToolRegistry` ¶

Central registry for all tools available to agents.

Tools are registered by name and can be retrieved individually or exported as a list of ToolDefinition objects for passing to a ModelClient.

`register(fn, *, name, description, parameters=None, version='1.0.0')` ¶

Register a callable as a named tool.

Parameters:

Name	Type	Description	Default
`fn`	`Callable[..., Any]`	The callable to invoke when the tool is called.	required
`name`	`str`	Unique tool name.	required
`description`	`str`	Human-readable description.	required
`parameters`	`list[ToolParameter] \| None`	Optional list of ToolParameter specs.	`None`
`version`	`str`	Semantic version string.	`'1.0.0'`

Returns:

Type	Description
`RegisteredTool`	The RegisteredTool instance stored in the registry.

Raises:

Type	Description
`ToolError`	If a tool with name is already registered.

`tool(*, name, description, parameters=None, version='1.0.0')` ¶

Decorator that registers a function and returns it unchanged.

Usage::

@registry.tool(name="add", description="Add two numbers")
def add(a: int, b: int) -> int:
    return a + b

`get(name)` ¶

Return the RegisteredTool for name, or None if not found.

`get_or_raise(name)` ¶

Return the RegisteredTool for name, raising ToolNotFoundError if absent.

Raises:

Type	Description
`ToolNotFoundError`	If no tool with name is registered.

`list_all()` ¶

Return all registered tools in registration order.

`to_definitions()` ¶

Return ToolDefinition objects for all registered tools.

Suitable for passing directly to a ModelClient.

ToolExecutor¶

Executes tool calls with validation, timeout, retry, and idempotency.

`grampus.tools.executor.ToolExecutor` ¶

Executes tool calls from the registry with validation, retry, and idempotency.

Parameters:

Name	Type	Description	Default
`registry`	`ToolRegistry`	Source of registered tools.	required
`timeout_seconds`	`float`	Per-call execution timeout.	`30.0`
`max_retries`	`int`	How many times to retry on retriable errors (0 = no retry).	`2`
`retry_delay_seconds`	`float`	Sleep between retries.	`0.5`

`execute(tool_call)` `async` ¶

Execute tool_call, honouring idempotency, validation, and retry policy.

Returns:

Type	Description
`ToolResult`	ToolResult on success.

Raises:

Type	Description
`ToolNotFoundError`	If the tool name is not in the registry.
`ToolValidationError`	If required arguments are missing.
`ToolTimeoutError`	If the call exceeds timeout_seconds.
`Exception`	Any unretriable exception from the tool function after retries are exhausted.

`get_record(tool_call_id)` ¶

Return the execution record for tool_call_id, or None.

`all_records()` ¶

Return all stored execution records in insertion order.

MCP client¶

`grampus.tools.mcp_client.MCPClient` ¶

Client for an MCP-compatible tool server.

Communicates via JSON-RPC 2.0 over HTTP. The server must expose:

POST /tools/list — list available tools
POST /tools/call — invoke a tool

Parameters:

Name	Type	Description	Default
`server_url`	`str`	Base URL of the MCP server (no trailing slash).	required
`timeout_seconds`	`float`	HTTP request timeout in seconds.	`30.0`
`_http_client`	`AsyncClient \| None`	Optional pre-built AsyncClient (for testing).	`None`

`list_tools()` `async` ¶

Discover tools available on the MCP server.

Returns:

Type	Description
`list[ToolDefinition]`	List of ToolDefinition objects parsed from the server response.

`close()` `async` ¶

Close the underlying HTTP client.

Sandbox¶

`grampus.tools.sandbox.manager.SandboxManager` ¶

Coordinates sandboxed code execution.

Uses a Docker container when the Docker SDK is installed and the daemon is reachable; otherwise falls back to a local subprocess (development only).

Parameters:

Name	Type	Description	Default
`config`	`SandboxConfig \| None`	Sandbox configuration; defaults applied when None.	`None`

`grampus.tools.sandbox.code_executor.CodeExecutor` ¶

Executes LLM-generated Python in the sandbox with registered tools injected.

Tool callables cannot cross a Docker process boundary, so tool injection works only with the local fallback backend. In both cases, tools_called is populated by a regex scan of the code string — no runtime instrumentation.

Parameters:

Name	Type	Description	Default
`sandbox`	`SandboxManager`	SandboxManager to delegate execution to.	required
`tool_registry`	`ToolRegistry`	Registry whose tools are injected into the execution namespace.	required

`execute(code, *, extra_namespace=None)` `async` ¶

Execute code in the sandbox and return a structured result.

Parameters:

Name	Type	Description	Default
`code`	`str`	Python source code to execute.	required
`extra_namespace`	`dict[str, Any] \| None`	Additional variables merged into the execution namespace (local fallback only; ignored by Docker backend).	`None`

Returns:

Type	Description
`CodeExecutionResult`	CodeExecutionResult with output, duration, and tool call information.

Action guard¶

`grampus.tools.boundaries.ActionGuard` ¶

Enforces per-agent tool access boundaries, rate limits, and cost budgets.

Parameters:

Name	Type	Description	Default
`config`	`BoundaryConfig`	Boundary configuration for this agent.	required

Types¶

RegisteredTool¶

@dataclass
class RegisteredTool:
    name: str
    description: str
    definition: ToolDefinition
    fn: Callable[..., Awaitable[Any]]

ToolDefinition¶

`grampus.core.types.ToolDefinition` ¶

Bases: BaseModel

Full specification of a tool, including JSON-schema generation.

`to_function_schema()` ¶

Return an OpenAI/Anthropic-compatible function JSON schema.

ToolParameter¶

`grampus.core.types.ToolParameter` ¶

Bases: BaseModel

Describes a single parameter accepted by a tool.

ToolCall¶

`grampus.core.types.ToolCall` ¶

Bases: BaseModel

A request from the model to invoke a tool.

ToolResult¶

`grampus.core.types.ToolResult` ¶

Bases: BaseModel

The outcome of executing a tool call.

ToolExecutionRecord¶

@dataclass
class ToolExecutionRecord:
    tool_call_id: str
    tool_name: str
    arguments: dict[str, Any]
    result: ToolResult
    started_at: datetime
    duration_ms: int

to_function_schema() output¶

ToolDefinition.to_function_schema() returns an OpenAI/Anthropic-compatible JSON schema:

from grampus.core.types import ToolDefinition, ToolParameter

defn = ToolDefinition(
    name="get_weather",
    description="Get current weather for a city.",
    parameters=[
        ToolParameter(name="city", type="string", description="City name", required=True),
        ToolParameter(
            name="units",
            type="string",
            description="Temperature units",
            required=False,
            default="celsius",
            enum=["celsius", "fahrenheit"],
        ),
    ],
)

import json
print(json.dumps(defn.to_function_schema(), indent=2))

Output:

{
  "name": "get_weather",
  "description": "Get current weather for a city.",
  "parameters": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "City name"
      },
      "units": {
        "type": "string",
        "description": "Temperature units",
        "default": "celsius",
        "enum": ["celsius", "fahrenheit"]
      }
    },
    "required": ["city"]
  }
}

Tools API Reference¶

ToolRegistry¶

grampus.tools.registry.ToolRegistry ¶

register(fn, *, name, description, parameters=None, version='1.0.0') ¶

tool(*, name, description, parameters=None, version='1.0.0') ¶

get(name) ¶

get_or_raise(name) ¶

list_all() ¶

to_definitions() ¶

ToolExecutor¶

grampus.tools.executor.ToolExecutor ¶

execute(tool_call) async ¶

get_record(tool_call_id) ¶

all_records() ¶

MCP client¶

grampus.tools.mcp_client.MCPClient ¶

list_tools() async ¶

close() async ¶

Sandbox¶

grampus.tools.sandbox.manager.SandboxManager ¶

grampus.tools.sandbox.code_executor.CodeExecutor ¶

execute(code, *, extra_namespace=None) async ¶

Action guard¶

grampus.tools.boundaries.ActionGuard ¶

Types¶

RegisteredTool¶

ToolDefinition¶

grampus.core.types.ToolDefinition ¶

to_function_schema() ¶

ToolParameter¶

grampus.core.types.ToolParameter ¶

ToolCall¶

grampus.core.types.ToolCall ¶

ToolResult¶

grampus.core.types.ToolResult ¶

ToolExecutionRecord¶

to_function_schema() output¶

`grampus.tools.registry.ToolRegistry` ¶

`register(fn, *, name, description, parameters=None, version='1.0.0')` ¶

`tool(*, name, description, parameters=None, version='1.0.0')` ¶

`get(name)` ¶

`get_or_raise(name)` ¶

`list_all()` ¶

`to_definitions()` ¶

`grampus.tools.executor.ToolExecutor` ¶

`execute(tool_call)` `async` ¶

`get_record(tool_call_id)` ¶

`all_records()` ¶

`grampus.tools.mcp_client.MCPClient` ¶

`list_tools()` `async` ¶

`close()` `async` ¶

`grampus.tools.sandbox.manager.SandboxManager` ¶

`grampus.tools.sandbox.code_executor.CodeExecutor` ¶

`execute(code, *, extra_namespace=None)` `async` ¶

`grampus.tools.boundaries.ActionGuard` ¶

`grampus.core.types.ToolDefinition` ¶

`to_function_schema()` ¶

`grampus.core.types.ToolParameter` ¶

`grampus.core.types.ToolCall` ¶

`grampus.core.types.ToolResult` ¶