Tools

Tools are the primary mechanism through which an agent interacts with the outside world. When you give an agent a set of tools, the LLM decides which tool to call, with what arguments, and when. The agent loop orchestrates this cycle automatically: the LLM requests a tool call, the framework executes it, feeds the result back, and the LLM continues reasoning until it produces a final response. This page covers the full tool API — from creating and registering tools, through the contracts that govern them, to the execution lifecycle and error handling. For practical step-by-step guidance on building your own tools, see Building Tools.

Creating Tools With FunctionTool

The fastest way to create a tool is to wrap any PHP callable with FunctionTool::fromCallable(). The tool name, description, and parameter schema are all generated automatically from the function signature using reflection:

use Cognesy\Agents\Tool\Tools\FunctionTool;
use Cognesy\Schema\Attributes\Description;

#[Description('Look up the current weather for a given city')]
function get_weather(
    #[Description('City name, e.g. "Paris"')] string $city,
): string {
    return "Weather in {$city}: 72F, sunny";
}

$tool = FunctionTool::fromCallable(get_weather(...));
// @doctest id="45f6"

The #[Description] attribute on the function provides the tool description that the LLM sees. The same attribute on parameters documents individual arguments in the generated JSON schema. Named functions produce meaningful tool names; closures work too, but you should prefer named functions for clarity.

Tip: FunctionTool is the recommended starting point for most projects. It handles schema generation, argument passing, and result wrapping with zero boilerplate.

The Tools Collection

Tools are collected in the immutable Tools value object. Pass any number of ToolInterface implementations to its constructor, and the collection indexes them by name:

use Cognesy\Agents\Collections\Tools;
use Cognesy\Agents\Tool\Tools\FunctionTool;

function get_weather(string $city): string {
    return "Weather in {$city}: 72F, sunny";
}

$tools = new Tools(
    FunctionTool::fromCallable(get_weather(...)),
);
// @doctest id="e26c"

Querying the Collection

The Tools collection provides a rich query API for inspecting registered tools at runtime:

$tools->has('get_weather');   // bool -- check if a tool is registered
$tools->get('get_weather');   // ToolInterface -- retrieve by name (throws if missing)
$tools->names();              // ['get_weather', ...] -- all registered names
$tools->count();              // int -- number of tools
$tools->isEmpty();            // bool -- true when collection is empty
$tools->all();                // array<string, ToolInterface> -- keyed by name
$tools->descriptions();       // [['name' => ..., 'description' => ...], ...]
$tools->toToolSchema();       // ToolDefinitions -- schema collection sent to the LLM
// @doctest id="a950"

The descriptions() method returns an array of compact summaries (name and description) for each tool. The toToolSchema() method returns the full OpenAI-compatible function-calling schema array that gets sent to the LLM as part of the inference request.

Immutable Mutators

The Tools collection is immutable. Every mutation returns a new instance, leaving the original unchanged:

// Add a single tool
$tools = $tools->withTool($anotherTool);

// Add multiple tools at once
$tools = $tools->withTools($toolA, $toolB, $toolC);

// Remove a tool by name
$tools = $tools->withToolRemoved('get_weather');

// Merge two collections (tools from $other override same-named tools)
$tools = $tools->merge($otherToolsCollection);
// @doctest id="7737"

Registering Multiple Tools

Pass multiple tools to the Tools constructor. The LLM chooses which tool to call on each turn:

use Cognesy\Agents\Tool\Tools\FunctionTool;
use Cognesy\Agents\Collections\Tools;
use Cognesy\Schema\Attributes\Description;

#[Description('Get the current weather for a city')]
function get_weather(
    #[Description('City name')] string $city,
): string {
    return "Weather in {$city}: 72F, sunny";
}

#[Description('Evaluate a math expression')]
function calculate(
    #[Description('Math expression to evaluate')] string $expression,
): string {
    return (string) eval("return {$expression};");
}

$tools = new Tools(
    FunctionTool::fromCallable(get_weather(...)),
    FunctionTool::fromCallable(calculate(...)),
);
// @doctest id="c511"

Attaching Tools to an Agent

There are two ways to give tools to an agent: directly on the AgentLoop, or through the AgentBuilder capability system.

Direct Assignment

The AgentLoop provides withTools() (replacing the entire collection) and withTool() (appending a single tool) methods:

use Cognesy\Agents\AgentLoop;
use Cognesy\Agents\Data\AgentState;

$loop = AgentLoop::default()->withTools($tools);

$state = AgentState::empty()->withUserMessage('What is the weather in Paris?');
$result = $loop->execute($state);

echo $result->finalResponse()->toString();
// @doctest id="204e"

You can also add tools one at a time:

$loop = AgentLoop::default()
    ->withTool(FunctionTool::fromCallable(get_weather(...)))
    ->withTool(FunctionTool::fromCallable(calculate(...)));
// @doctest id="7f1d"

Via the AgentBuilder

The UseTools capability integrates tools through the builder’s composition layer. This is the preferred approach when assembling agents from reusable capabilities:

use Cognesy\Agents\Builder\AgentBuilder;
use Cognesy\Agents\Capability\Core\UseTools;

$loop = AgentBuilder::base()
    ->withCapability(new UseTools(
        FunctionTool::fromCallable(get_weather(...)),
        FunctionTool::fromCallable(calculate(...)),
    ))
    ->build();
// @doctest id="b6dc"

UseTools merges the provided tools into any tools already registered on the builder, so you can combine multiple UseTools capabilities without overwriting earlier registrations.

Tool Contracts

The tool system is built on a small set of interfaces. Understanding them helps when you need to go beyond the basics and build custom tool implementations.

ToolInterface

Every tool implements ToolInterface, which defines the three things the framework needs from a tool:

interface ToolInterface {
    public function use(mixed ...$args): Result;         // Execute the tool
    public function toToolSchema(): ToolDefinition;      // Schema sent to the LLM
    public function descriptor(): CanDescribeTool;       // Metadata accessor
}
// @doctest id="2d8c"

The use() method receives the arguments that the LLM provided and returns a Result object wrapping either a success value or a failure. The toToolSchema() method returns a ToolDefinition value object describing the tool’s name, description, and parameters. The descriptor() method returns the tool’s identity and documentation.

CanDescribeTool

The descriptor interface provides identity and documentation at two levels of detail:

interface CanDescribeTool {
    public function name(): string;          // Tool name (e.g., 'read_file')
    public function description(): string;   // What the tool does
    public function metadata(): array;       // Lightweight info for browsing/discovery
    public function instructions(): array;   // Full specification with parameters
}
// @doctest id="cf72"

metadata() returns a compact summary suitable for listing tools. The default implementation includes name and summary keys, with an optional namespace key for namespaced tool names (e.g., file.read yields namespace file). instructions() returns the complete specification including parameter definitions and return type. This two-level design supports tool registries where an agent can browse available tools before loading their full documentation.

CanAccessAgentState

Tools that need to read the current agent execution state implement CanAccessAgentState. The framework calls withAgentState() before each invocation, passing in the current AgentState. The method returns a new (cloned) instance with the state injected:

interface CanAccessAgentState {
    public function withAgentState(AgentState $state): static;
}
// @doctest id="fbfc"

State is read-only from the tool’s perspective. The withAgentState() method clones the tool and injects the state, ensuring that tool instances remain safe to reuse across invocations. Modifications to agent state should be handled by the agent’s state processors, not by tools directly.

CanAccessToolCall

Tools that need access to their invocation context (the raw ToolCall object with its ID and arguments) implement CanAccessToolCall. This is useful for correlation, tracing, logging, and subagent tools that emit events:

interface CanAccessToolCall {
    public function withToolCall(ToolCall $toolCall): static;
}
// @doctest id="3382"

Like CanAccessAgentState, this method clones the tool and injects the ToolCall, preserving immutability.

CanManageTools

The CanManageTools interface defines the contract for mutable tool registries that support lazy instantiation through factories:

interface CanManageTools {
    public function register(ToolInterface $tool): void;
    public function registerFactory(string $name, callable $factory): void;
    public function has(string $name): bool;
    public function get(string $name): ToolInterface;
    public function all(): array;
    public function names(): array;
    public function count(): int;
}
// @doctest id="1a51"

The ToolRegistry class implements this interface and is used internally by the ToolsTool capability for dynamic tool discovery. The registerFactory() method accepts a callable(): ToolInterface that is only invoked when the tool is first requested, enabling lazy loading of expensive tools.

CanExecuteToolCalls

The CanExecuteToolCalls interface defines the contract for executing a batch of tool calls against a given agent state:

interface CanExecuteToolCalls {
    public function executeTools(ToolCalls $toolCalls, AgentState $state): ToolExecutions;
}
// @doctest id="ec9e"

The ToolExecutor class is the default implementation, and the AgentLoop accepts a custom executor via withToolExecutor().

The Tool Class Hierarchy

The framework provides a layered set of abstract base classes. Each layer adds a specific concern, so you can extend at the level of abstraction that fits your use case:

Class	What it adds	When to use
`SimpleTool`	Descriptor + result wrapper + `$this->arg()` helper	Full manual control over everything
`ReflectiveSchemaTool`	Auto-generates `toToolSchema()` via reflection	When you want schema from `__invoke` signature
`FunctionTool`	Wraps a callable with cached reflective schema	Typed callable tools (most common)
`StateAwareTool`	`withAgentState()` / `$this->agentState`	When you need to read execution state
`BaseTool`	State + reflective schema + default metadata/instructions	State-aware class-based tools
`ContextAwareTool`	State + `withToolCall()` / `$this->toolCall`	When you need raw tool call context

The inheritance chain flows as follows:

SimpleTool                              # descriptor, result wrapping, arg()
  +-- ReflectiveSchemaTool              # auto toToolSchema() from __invoke
  |     +-- FunctionTool                # wraps callable + cached schema
  +-- StateAwareTool                    # + CanAccessAgentState
        +-- BaseTool                    # + reflective schema + metadata/instructions
        +-- ContextAwareTool            # + CanAccessToolCall
// @doctest id="9e36"

For most projects, FunctionTool or BaseTool is all you need. See Building Tools for practical guidance, and Building Tools: Advanced Patterns for lower-level patterns.

How Tool Execution Works

The ToolExecutor manages the full lifecycle of a tool call. Understanding this flow helps when debugging or customizing tool behavior.

1. Schema Delivery

The Tools collection serializes all tool schemas via toToolSchema() and sends them to the LLM as part of the inference request. Each schema follows the OpenAI function-calling format:

[
    'type' => 'function',
    'function' => [
        'name' => 'get_weather',
        'description' => 'Get the current weather for a city',
        'parameters' => [
            'type' => 'object',
            'properties' => [...],
            'required' => [...],
        ],
    ],
]
// @doctest id="7e4d"

2. Tool Call Parsing

When the LLM responds with one or more tool calls, the framework parses them into ToolCall objects containing the tool name, call ID, and arguments.

3. Hook Interception (Before)

Before executing each tool call, the ToolExecutor runs the beforeToolUse lifecycle hook via the interceptor. Hooks can:

Modify the tool call (e.g., rewrite arguments).
Modify the agent state (e.g., inject context).
Block execution entirely by marking the hook context as blocked. When blocked, a ToolExecution::blocked() result is returned without invoking the tool.

If the stopOnToolBlock option is enabled on the ToolExecutor, the entire batch stops after the first blocked tool call.

4. Tool Preparation

The executor looks up the tool by name from the Tools collection. If the tool implements CanAccessAgentState, a clone with the current AgentState injected is created. If it implements CanAccessToolCall, the raw ToolCall is injected the same way. This ensures tools are stateless and safe for concurrent use.

5. Argument Validation

Required parameters declared in the tool’s schema are checked against the provided arguments. Missing required parameters produce a Result::failure() with an InvalidToolArgumentsException without invoking the tool. The LLM sees the error message and can retry with corrected arguments.

6. Execution

The tool’s use() method is called with the LLM-provided arguments. For tools extending SimpleTool, this delegates to __invoke(), and the return value is automatically wrapped in Result::success(). Any exception (except AgentStopException) is caught and wrapped in Result::failure().

7. Event Emission

The executor dispatches ToolCallStarted and ToolCallCompleted events around each execution. These events carry timing information and success/failure status, making them useful for logging, metrics, and observability.

8. Hook Interception (After)

The afterToolUse lifecycle hook runs, allowing inspection or modification of the execution result. Hooks can replace the ToolExecution entirely (e.g., to sanitize output or add metadata).

9. Result Formatting

Tool execution results are formatted as messages and appended to the conversation. The LLM sees these results on its next turn.

10. Loop Continuation

The cycle repeats until the LLM responds without requesting any tool calls, at which point the agent produces its final response.

The ToolExecution Object

Each tool invocation produces a ToolExecution value object that captures the complete execution record:

$execution->id();            // ToolExecutionId -- unique identifier
$execution->toolCall();      // ToolCall -- the original call from the LLM
$execution->name();          // string -- tool name shortcut
$execution->args();          // array -- arguments shortcut
$execution->result();        // Result -- success or failure
$execution->value();         // mixed -- unwrapped success value, or null
$execution->error();         // ?Throwable -- exception on failure, or null
$execution->errorMessage();  // string -- error message, or empty string
$execution->hasError();      // bool -- true if execution failed
$execution->wasBlocked();    // bool -- true if blocked by a hook
$execution->startedAt();     // DateTimeImmutable
$execution->completedAt();   // DateTimeImmutable
$execution->toArray();       // array -- serializable representation
// @doctest id="fe25"

The ToolExecutions collection aggregates multiple executions from a single step and provides batch-level queries:

$executions->all();           // ToolExecution[]
$executions->first();         // ?ToolExecution
$executions->hasExecutions(); // bool
$executions->hasErrors();     // bool
$executions->havingErrors();  // ToolExecution[] -- only failed ones
$executions->errors();        // ErrorList
$executions->toolCalls();     // ToolCalls -- extract original calls
// @doctest id="72f1"

Error Handling

Tool failures are handled gracefully by default. If a tool throws an exception, the framework catches it, wraps it in a Result::failure() with a ToolExecutionException, and reports the error back to the LLM as a tool result. This lets the LLM retry with different arguments or fall back to an alternative approach. The AgentStopException is the one exception that is never caught. Throwing it from within a tool immediately stops the agent loop with the provided StopSignal. This is the canonical way for a tool to halt execution programmatically.

Strict Failure Mode

You can change the default behavior with the throwOnToolFailure option on the ToolExecutor. When enabled, tool exceptions propagate and halt the agent loop instead of being fed back to the LLM:

$executor = new ToolExecutor(
    tools: $tools,
    events: $events,
    interceptor: $interceptor,
    throwOnToolFailure: true,
);
// @doctest id="1312"

Stopping on Blocked Tools

The stopOnToolBlock option causes the executor to stop processing remaining tool calls in a batch when a hook blocks the first one:

$executor = new ToolExecutor(
    tools: $tools,
    events: $events,
    interceptor: $interceptor,
    stopOnToolBlock: true,
);
// @doctest id="6bce"

The Tool Registry

For scenarios where tools are numerous or expensive to instantiate, the ToolRegistry provides a mutable, lazy-loading container that implements CanManageTools:

use Cognesy\Agents\Tool\ToolRegistry;

$registry = new ToolRegistry();

// Register a tool instance directly
$registry->register($myTool);

// Register a factory for lazy instantiation
$registry->registerFactory('expensive_tool', function () {
    return new ExpensiveTool(/* ... */);
});

// The tool is only instantiated when first requested
$tool = $registry->get('expensive_tool');
// @doctest id="8bde"

The ToolRegistry is used internally by the ToolsTool capability, which exposes a meta-tool that lets the LLM browse, search, and inspect available tools at runtime.

FakeTool for Testing

When testing agent behavior, use FakeTool to create tools with predetermined responses. This avoids external dependencies and makes tests deterministic.

Static Responses

The simplest form returns the same value regardless of arguments:

use Cognesy\Agents\Tool\Tools\FakeTool;

$tool = FakeTool::returning('search', 'Search the web', 'result text');
// @doctest id="9f77"

Dynamic Responses

Pass a callable handler for responses that depend on the arguments:

$tool = new FakeTool(
    name: 'search',
    description: 'Search the web',
    handler: fn(string $query) => "Results for: {$query}",
);
// @doctest id="c3d6"

Full Customization

FakeTool also accepts optional schema, metadata, and fullSpec arrays for complete control over how the fake tool presents itself:

$tool = new FakeTool(
    name: 'search',
    description: 'Search the web',
    handler: fn(string $query) => "Results for: {$query}",
    schema: [
        'type' => 'function',
        'function' => [
            'name' => 'search',
            'description' => 'Search the web',
            'parameters' => [
                'type' => 'object',
                'properties' => [
                    'query' => ['type' => 'string', 'description' => 'Search query'],
                ],
                'required' => ['query'],
            ],
        ],
    ],
    metadata: [
        'namespace' => 'web',
        'tags' => ['search'],
    ],
    fullSpec: [
        'parameters' => [
            'query' => 'The search query string',
        ],
        'returns' => 'Search results as a string',
    ],
);
// @doctest id="49ad"

When no custom schema is provided, FakeTool generates a minimal schema with an empty properties object, which is sufficient for most testing scenarios.

Next Steps

Building Tools — practical guide to creating tools with FunctionTool and BaseTool
Building Tools: Advanced Patterns — ContextAwareTool, SimpleTool, descriptors, and schema strategies
Hooks — intercepting tool calls with beforeToolUse and afterToolUse hooks

Packages

Instructor

Polyglot

Agents

Agent-ctrl

Telemetry

Sandbox

HTTP Client

Laravel

Symfony

Xprompt

​Tools

​Creating Tools With FunctionTool

​The Tools Collection

​Querying the Collection

​Immutable Mutators

​Registering Multiple Tools

​Attaching Tools to an Agent

​Direct Assignment

​Via the AgentBuilder

​Tool Contracts

​ToolInterface

​CanDescribeTool

​CanAccessAgentState

​CanAccessToolCall

​CanManageTools

​CanExecuteToolCalls

​The Tool Class Hierarchy

​How Tool Execution Works

​1. Schema Delivery

​2. Tool Call Parsing

​3. Hook Interception (Before)

​4. Tool Preparation

​5. Argument Validation

​6. Execution

​7. Event Emission

​8. Hook Interception (After)

​9. Result Formatting

​10. Loop Continuation

​The ToolExecution Object

​Error Handling

​Strict Failure Mode

​Stopping on Blocked Tools

​The Tool Registry

​FakeTool for Testing

​Static Responses

​Dynamic Responses

​Full Customization

​Next Steps