Tool Modules

This page documents the stable public tool runtime facade.

Stable public tool runtime exports.

class design_research_agents.tools.CallableToolConfig(*, name, description, handler, input_schema=<factory>, output_schema=<factory>, permissions=(), risky=None)

Simple in-process callable tool wrapper descriptor.

description

Short description of the tool’s behavior.

handler

Python callable that implements the tool’s behavior. It should accept a single argument of type Mapping[str, object] and return an arbitrary JSON-serializable object.

input_schema

JSON Schema describing the expected input structure for the tool. This is used for validation and documentation purposes.

name

Unique name of the tool.

output_schema

JSON Schema describing the structure of the tool’s output. This is used for validation and documentation purposes.

permissions

Optional tuple of permission strings that the tool requires. This can be used to enforce security constraints or to inform users about the tool’s capabilities.

risky

Whether the tool performs potentially risky operations.

class design_research_agents.tools.MCPServerConfig(*, id, type='stdio', command=(), timeout_s=20, env_allowlist=('PATH', 'HOME', 'USER', 'LANG', 'LC_ALL', 'PYTHONPATH', 'VIRTUAL_ENV'), env=<factory>)

External MCP server definition.

command

Command to launch the server, specified as a tuple of strings. The first element should be the executable, and the subsequent elements are its arguments.

env

Explicit environment variables to set for the server process. This is a mapping of variable names to their desired values. These variables will be included in the server’s environment in addition to any variables from the allowlist that are present in the parent process.

env_allowlist

Allowlist of environment variable names that will be passed to the server process. Only variables in this list will be included in the server’s environment, which helps to limit exposure of sensitive information and reduce the attack surface.

id

Unique identifier for the server. This is used to reference the server in tool definitions and logs.

timeout_s

Timeout in seconds for server responses before treating it as unresponsive.

type

Communication protocol to use with the server. Currently, only ‘stdio’ is supported, which means the server will be launched as a subprocess and communicated with via its standard input and output streams.

class design_research_agents.tools.ScriptToolConfig(*, name, path, description, input_schema=<factory>, output_schema=<factory>, filesystem_read=False, filesystem_write=False, network=False, commands=(), timeout_s=30, permissions=(), risky=None)

One explicit script-backed tool definition.

commands

Optional tuple of allowed shell commands that the tool is permitted to execute. If non-empty, the tool will only be allowed to execute commands in this list, and attempts to execute any other commands will be blocked. This is used to enforce security constraints and limit the tool’s capabilities.

description

Short description of the tool’s behavior. This should be a concise summary of what the tool does, suitable for inclusion in prompts and documentation.

filesystem_read

Flag indicating whether the tool needs read access to the filesystem. If True, the tool will be granted read access to the workspace root and artifacts directory. If False, the tool will not be granted any filesystem access. This is used to enforce security constraints and limit the tool’s capabilities.

filesystem_write

Flag indicating whether the tool needs write access to the filesystem. If True, the tool will be granted write access to the workspace root and artifacts directory. If False, the tool will not be granted any filesystem access. This is used to enforce security constraints and limit the tool’s capabilities.

input_schema

JSON Schema describing the expected input structure for the tool. This is used for validation and documentation purposes. The tool will receive its input as a JSON-encoded string on its standard input, and it should produce its output as a JSON-encoded string on its standard output. The input schema should describe the structure of the JSON object that the tool expects to receive, including any required properties and their types.

name

Unique name of the tool. This is used to reference the tool in prompts and logs.

network

Flag indicating whether the tool needs access to the network. If True, the tool will be granted access to the network. If False, the tool will not be granted any network access. This is used to enforce security constraints and limit the tool’s capabilities.

output_schema

JSON Schema describing the structure of the tool’s output. This is used for validation and documentation purposes. The tool’s output should be a JSON-encoded string written to its standard output, and the output schema should describe the structure of the JSON object that the tool produces, including any properties and their types.

path

Filesystem path to the script that implements the tool’s behavior. This should be an absolute path or a path relative to the configured workspace root. The script will be executed as a subprocess when the tool is invoked, and communicated with via its standard input and output streams.

permissions

Optional tuple of permission strings that the tool requires. This can be used to enforce security constraints or to inform users about the tool’s capabilities. The specific permission strings and their meanings are not defined by this configuration and should be interpreted by the tool runtime or the user interface accordingly.

risky

Optional boolean flag indicating whether the tool performs potentially risky operations, such as executing shell commands, accessing the filesystem, or making network requests. This can be used to inform users about the tool’s capabilities and potential risks.

timeout_s

Timeout in seconds for the tool’s execution. If the tool does not produce output within this time frame, it will be considered unresponsive, and appropriate error handling will be triggered.

class design_research_agents.tools.ToolResult(*, tool_name, ok, result=None, artifacts=(), warnings=(), error=None, metadata=None)

Result payload emitted from a tool runtime invocation.

Initialize canonical tool result payload.

Parameters:

• tool_name – Name of the invoked tool.

• ok – Invocation success flag.

• result – Primary result payload (defaults to empty mapping).

• artifacts – Raw or typed artifact entries to normalize.

• warnings – Warning messages to attach to the result.

• error – Error payload to normalize into ToolError.

• metadata – Optional diagnostic metadata mapping.

property artifact_paths

Return artifact paths in emitted order.

Returns:

Tuple of artifact path strings.

artifacts

Artifact list emitted by the invocation.

error

Structured error details when ok is false.

property error_message

Return the normalized tool error message when present.

Returns:

Error message string, or None.

metadata

Supplemental runtime metadata for diagnostics and tracing.

ok

True when invocation succeeded.

result

Primary tool return payload.

result_dict()

Return the primary result payload normalized to a dictionary.

Returns:

Dictionary value when result is mapping-like, else {}.

result_list()

Return the primary result payload normalized to a list.

Returns:

List value when result is a list/tuple, else [].

tool_name

Name of the invoked tool.

warnings

Non-fatal warnings produced during invocation.

class design_research_agents.tools.Toolbox(*, workspace_root='.', enable_core_tools=True, script_tools=None, callable_tools=None, mcp_servers=None)

Tool runtime that routes calls across enabled tool sources.

Initialize toolbox sources from ergonomic constructor arguments.

Parameters:

• workspace_root – Root directory for tools that interact with the filesystem.

• enable_core_tools – Whether to enable the built-in core tools.

• script_tools – Optional tuple of ScriptToolConfig definitions to expose through a script tool source.

• callable_tools – Optional tuple of CallableToolConfig definitions to register as in-process tools.

• mcp_servers – Optional tuple of MCP server definitions to connect to and expose tools from.

close()

Release external source resources.

property config

Return active runtime configuration.

Returns:

Fully resolved runtime configuration for this toolbox.

invoke(tool_name, input, *, request_id, dependencies)

Invoke one tool through the registry routing layer.

Parameters:

• tool_name – Name of the tool to invoke. This will be normalized by stripping leading and trailing whitespace before lookup.

• input – Mapping of input values to provide for this tool invocation. This will be validated against the tool’s input schema before invocation.

• request_id – Request ID to associate with this tool invocation, which will be passed through to the underlying tool handler and can be used for logging, tracing, and other purposes.

• dependencies – Mapping of dependencies to provide for this tool invocation, which will be passed through to the underlying tool handler and can be used to provide additional context or resources needed for the tool execution.

Returns:

The result of the tool invocation, as returned by the underlying tool handler. This will be validated against the tool’s output schema before being returned to the caller.

invoke_dict(tool_name, input, *, request_id, dependencies)

Invoke one tool and require a successful dictionary payload.

Parameters:

• tool_name – Name of the tool to invoke.

• input – Tool input payload mapping.

• request_id – Request identifier associated with this invocation.

• dependencies – Dependency payload mapping for this invocation.

Returns:

Tool result mapping.

Raises:

RuntimeError – If invocation fails or result payload is not a mapping.

list_tools()

List all tools currently exposed by enabled runtime sources.

Returns:

Sequence of ToolSpec objects representing all tools currently exposed by enabled runtime sources, in no particular order.

register_callable_tool(callable_tool)

Register one callable tool wrapper.

Parameters:

callable_tool – CallableToolConfig definition to register. The name field will be normalized by stripping leading and trailing whitespace, and must be non-empty after normalization.

Returns:

None

Raises:

Exception – Raised when this operation cannot complete.

register_tool(*, spec, handler)

Register a custom in-process tool.

Parameters:

• spec – ToolSpec defining the tool to register. The name field will be normalized by stripping leading and trailing whitespace, and must be non-empty after normalization.

• handler – ToolHandler function to execute when this tool is invoked. The handler will be wrapped to match the expected signature for in-process tools, which includes additional parameters for request ID and dependencies that will be ignored by the provided handler.

Returns:

None

property registry

Return the source-merging registry.

Returns:

Registry that owns source routing and invocation dispatch.