Add an AI tool

Tools are what a chat model can call while answering: search the web, read a page, generate an image, look something up in a knowledge base. A tool is a small class with a JSON schema and a call() method.

Read what the core will and won’t offer before you build. A brand-new tool key can be registered, but the built-in chat flow only offers tools whose key appears in the plan configuration, and that list is fixed. Your options are to replace an existing tool’s implementation, or to call your tool from your own plugin’s flows.

The interface

namespace Ai\Infrastructure\Services\Tools;

interface ToolInterface
{
    public function isEnabled(): bool;
    public function getDescription(): string;
    public function getDefinitions(): array;

    public function call(
        ConversationEntity $conversation,
        WorkspaceEntity $workspace,
        UserEntity $user,
        ?AssistantEntity $assistant = null,
        ?array $params = null,
    ): CallResponse;

    public function getSystemInstructions(?MessageEntity $message = null): ?string;
}

Method	Purpose
`isEnabled()`	Whether the tool is configured and switched on
`getDescription()`	What the tool does, sent to the model so it knows when to call it
`getDefinitions()`	JSON Schema for the arguments
`call()`	Runs the tool and returns its result and cost
`getSystemInstructions()`	Extra system prompt text, or `null`

Implementation

src/Tools/WeatherTool.php

<?php

declare(strict_types=1);

namespace Acme\Weather\Tools;

use Acme\Weather\Client;
use Ai\Domain\Entities\ConversationEntity;
use Ai\Domain\Entities\MessageEntity;
use Ai\Infrastructure\Services\Tools\CallException;
use Ai\Infrastructure\Services\Tools\CallResponse;
use Ai\Infrastructure\Services\Tools\ToolInterface;
use Assistant\Domain\Entities\AssistantEntity;
use Billing\Domain\ValueObjects\CreditCount;
use Easy\Container\Attributes\Inject;
use Override;
use Throwable;
use User\Domain\Entities\UserEntity;
use Workspace\Domain\Entities\WorkspaceEntity;

class WeatherTool implements ToolInterface
{
    public const LOOKUP_KEY = 'acme_weather';

    public function __construct(
        private Client $client,

        #[Inject('option.acme_weather.api_key')]
        private ?string $apiKey = null,
    ) {}

    #[Override]
    public function isEnabled(): bool
    {
        return (bool) $this->apiKey;
    }

    #[Override]
    public function getDescription(): string
    {
        return 'Look up the current weather for a city.';
    }

    #[Override]
    public function getDefinitions(): array
    {
        return [
            'type' => 'object',
            'properties' => [
                'city' => [
                    'type' => 'string',
                    'description' => 'City name, optionally with a country code.',
                ],
            ],
            'required' => ['city'],
        ];
    }

    #[Override]
    public function getSystemInstructions(?MessageEntity $message = null): ?string
    {
        return 'Use the weather tool whenever the user asks about current conditions.';
    }

    #[Override]
    public function call(
        ConversationEntity $conversation,
        WorkspaceEntity $workspace,
        UserEntity $user,
        ?AssistantEntity $assistant = null,
        ?array $params = null,
    ): CallResponse {
        $city = $params['city'] ?? null;

        if (!$city) {
            throw new CallException('No city was provided.');
        }

        try {
            $weather = $this->client->current($city);
        } catch (Throwable $th) {
            throw new CallException('Weather lookup failed.', previous: $th);
        }

        // Return text the model can read, plus what the call cost.
        return new CallResponse(
            content: sprintf('%s: %s, %d°C', $city, $weather->summary, $weather->temp),
            cost: new CreditCount(0),
        );
    }
}

CallResponse takes the text result, the cost in credits, and optionally a library item when your tool produced something like an image.

Writing a good tool

Describe it for a model, not a human. Say when to use it and what it returns.
Keep the schema small. Few parameters, clear names, explicit required.
Return text. The content goes back into the conversation, so make it readable and compact.
Be fast, and time out. A slow tool stalls the whole answer.
Throw CallException for failures, so the model sees an error instead of a broken stream.
Charge for expensive work with CostCalculator, and return the amount in the response.

Register the tool

src/Plugin.php

use Acme\Weather\Tools\WeatherTool;
use Ai\Infrastructure\Services\Tools\ToolCollection;

public function __construct(
    private ToolCollection $tools,
) {}

public function boot(Context $context): void
{
    $this->tools->add(WeatherTool::LOOKUP_KEY, WeatherTool::class);
}

What the core offers to models

When a message is generated, the tool collection decides which tools to expose. It checks, in order:

isEnabled() on the tool.
Whether the conversation is temporary, which disables context tools such as memory and canvas.
Whether the plan’s tool configuration has the tool’s key enabled.
Whether the user disabled that capability in their preferences.

Step 3 is the limit: Billing\Domain\ValueObjects\PlanConfig builds its tools map from a fixed list of keys.

Key	Capability
`embedding_search`	Search uploaded files
`google_search`	Web search
`youtube`	YouTube lookups
`web_scrap`	Fetch a web page
`generate_media`	Images, video, speech and transcription
`memory`	Memories and chat history
`canvas`	Canvas documents
`ask_questions`	Interactive follow-up questions

A key outside that list is never enabled on a plan, so the collection never yields it to the model.

What you can do instead

Replace a built-in tool's implementation

Register your class under an existing key, such as google_search, to swap the provider behind a capability administrators already control. Keep the same argument schema so existing prompts keep working.

Call the tool from your own flow

If your plugin runs its own AI flow, for example an assistant of your own, you own the tool loop: build the definitions, call your tool when the model asks for it, and feed the result back. Nothing restricts which tools you offer there.

Do the work before the model runs

Some “tools” are better as context. Fetch what’s needed and add it to the system instructions rather than waiting for the model to ask.

Testing

With the capability enabled on the plan, the model calls your tool when it should.

The tool’s result appears in the answer, and the tool call is shown in the transcript.

A failure produces a graceful message rather than a broken response.

Credits are charged when the tool costs money.

Get Started

Plugins

Extension Guides

Themes

Core Architecture

REST API

The interface

Implementation

Writing a good tool

Register the tool

What the core offers to models

What you can do instead

Testing

​The interface

​Implementation

​Writing a good tool

​Register the tool

​What the core offers to models

​What you can do instead

​Testing

​Related

The interface

Implementation

Writing a good tool

Register the tool

What the core offers to models

What you can do instead

Testing

Related