Tools#

Supporting classes and functions for creating and using tools, including ToolSpec. See Tools for the built-in tools, and Custom Tools for writing your own.

class gptme.tools.Parameter#

A wrapper for function parameters to convert them to JSON schema.

__init__(name: str, type: str, description: str | None = None, enum: list[Any] | None = None, required: bool = False) → None#

class gptme.tools.ToolFunction#

A structured callable exposed as a tool function, independent of execution runtime.

Replaces bare Callable entries in ToolSpec.functions with explicit metadata so prompt rendering, IPython registration, and future runtimes all consume the same description instead of introspecting raw Python objects.

Parameters:

name – Function name used in prompts and lookups.
fn – The actual callable to invoke.
description – Human-readable description shown in the tool prompt.
group – Logical grouping (e.g. “discord”, “github”) for allowlist patterns.
parameters – Explicit parameter schema; if empty, derived from fn’s annotations.
hints – Capability tags (e.g. {"read-only"}, {"destructive"}).

__init__(name: str, fn: ~collections.abc.Callable, description: str = '', group: str | None = None, parameters: list[~gptme.tools.base.Parameter] = <factory>, hints: frozenset[str] = <factory>) → None#

classmethod from_callable(fn: Any, group: str | None = None) → ToolFunction#

Construct a ToolFunction from a plain callable, inferring metadata.

Populates name, description (first docstring paragraph), and parameters (from type annotations + inspect.signature). No IPython import required.

class gptme.tools.ToolSpec#

Tool specification. Defines a tool that can be used by the agent.

Parameters:

name – The name of the tool.
desc – A description of the tool.
instructions – Instructions for the agent on how to use the tool. This will be included in the prompt.
instructions_format – Per tool format instructions when needed.
examples – Example usage of the tool.
functions – Functions registered in the IPython REPL.
init – An optional function that is called when the tool is first loaded.
execute – An optional function that is called when the tool executes a block.
block_types – A list of block types that the tool will execute.
available – Whether the tool is available for use.
available_hint – Optional guidance shown when the tool is explicitly requested but currently unavailable (e.g. “start the TTS server”).
parameters – Descriptor of parameters use by this tool.
load_priority – Influence the loading order of this tool. The higher the later.
disabled_by_default – Whether this tool should be disabled by default.
requires_tools – Names of companion tools that are loaded together with this one (a tool whose docs or workflow depend on another tool).
hooks – Hooks to register when this tool is loaded.
commands – User slash-commands (/example) to register when this tool is loaded.

__init__(name: str, desc: str, instructions: str = '', instructions_format: dict[str, str] | None = None, examples: str | Callable[[str], str] = '', functions: Sequence[ToolFunctionInput] | None = None, init: InitFunc | None = None, execute: ExecuteFunc | None = None, block_types: list[str] | None = None, available: bool | Callable[[], bool] = True, available_hint: str | None = None, parameters: list[Parameter] | None = None, load_priority: int = 0, disabled_by_default: bool = False, requires_tools: list[str] | None = None, is_mcp: bool = False, hints: frozenset[str] | None = None, read_only: bool = False, hooks: dict[str, tuple[str, HookFunc, int]] | None = None, commands: dict[str, Callable] | None = None)#

as_function_subtoolspecs() → list[ToolSpec]#

Expand each ToolFunction into its own independently invocable ToolSpec.

Returns one ToolSpec per ToolFunction, each with a direct execute handler that calls fn(**kwargs) without requiring IPython. Sub-spec names follow the <parent>.<function_name> pattern, which mirrors the MCP tool naming convention (e.g. discord.send_message).

This allows agents to invoke helper functions even when the IPython tool is not loaded.

Example:

for sub in browser_tool.as_function_subtoolspecs():
    if sub.name == "browser.view_image":
        list(sub.execute(None, None, {"path": "screenshot.png"}))

classmethod from_function(fn: Callable) → ToolSpec#

Create a ToolSpec from a plain Python function.

Auto-generates name, description, and parameters from the function signature and docstring. The returned ToolSpec has an execute handler that calls fn(**kwargs) directly — no IPython required.

Note: All values received via the kwargs channel are strings (dict[str, str]). Functions whose parameters require non-string types (int, float, bool, etc.) must perform their own coercion inside the function body.

get_doc(doc: str | None = None) → str#: Returns an updated docstring with examples.

property is_available: bool#: Check if the tool is available for use.

property is_runnable: bool#: Check if the tool can be executed.

register_commands() → None#: Register all commands defined in this tool with the global command registry.

register_hooks() → None#: Register all hooks defined in this tool with the global hook registry.

class gptme.tools.ToolUse#

__init__(tool: str, args: list[str] | None, content: str | None, kwargs: dict[str, str] | None = None, call_id: str | None = None, start: int | None = None, _format: Literal['markdown', 'xml', 'tool'] | None = 'markdown') → None#

execute(log: Log | None = None, workspace: Path | None = None, on_result_message: Callable[[Message], None] | None = None) → Generator[Message, None, None]#: Executes a tool-use tag and returns the output.

classmethod iter_from_content(content: str, tool_format_override: Literal['markdown', 'xml', 'tool'] | None = None, streaming: bool = False) → Generator[ToolUse, None, None]#

Returns all ToolUse in a message, markdown or XML, in order.

Parameters:

content – The message content to parse
tool_format_override – Optional tool format override
streaming – If True, requires blank line after code blocks for completion

Tools

Contents

Tools#