---
title: "Tools"
description: "Let a Workers AI model call your PHP tools. Pick a model that calls them, and force a call when needed."
---

> Documentation Index
> Fetch the complete documentation index at: https://laravel-cf-workersai.meirdick.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools

You write tools with the standard Laravel AI interfaces, and the package turns each one into an OpenAI-style function definition.

## Define a tool and an agent

```php
use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Contracts\Tool;
use Laravel\Ai\Promptable;
use Laravel\Ai\Tools\Request;

class GetWeather implements Tool
{
    public function description(): string
    {
        return 'Look up the current weather.';
    }

    public function handle(Request $request): string
    {
        return "Sunny in {$request['city']}.";
    }

    public function schema(JsonSchema $schema): array
    {
        return ['city' => $schema->string()->required()];
    }
}

class WeatherAgent implements Agent, HasTools
{
    use Promptable;

    public function instructions(): string
    {
        return 'Use the tool to answer weather questions.';
    }

    public function tools(): iterable
    {
        return [new GetWeather];
    }
}

(new WeatherAgent)->prompt('Weather in Tokyo?', provider: 'workers-ai');
```

## What the package does

- It sends `tool_choice: auto` when the agent has tools.
- A tool with no parameters works. The package sends an empty `properties` object, because Workers AI rejects an empty array.
- It keeps the reasoning text from a tool-call turn and sends it back on the next turn.
- It supports sub-agents and MCP tools. When a tool has a `name()` method, the package uses that name, so two instances of one class don't collide.
- It encodes array tool results as JSON without escaping slashes or unicode.

## Choose a model for tools

Not every model calls tools. In tests on 2026-06-11 on the direct API, on one account:

| Model | Tool calls |
| --- | --- |
| `@cf/meta/llama-3.3-70b-instruct-fp8-fast` (default) | Answers in prose. Does not call tools on the `/v1` endpoint. |
| `@cf/meta/llama-4-scout-17b-16e-instruct` | Calls tools. |
| `@cf/openai/gpt-oss-120b` | Calls tools. |

If your agent uses tools, set the model on the agent or the call, because the default model won't call them.

## Force a tool call

With `tool_choice: auto`, open-weight models call a tool only some of the time. To force a call, return `tool_choice` from `providerOptions()`:

```php
use Laravel\Ai\Enums\Lab;

// Inside your agent class:
public function providerOptions(Lab|string $provider): array
{
    return $provider === 'workers-ai' ? ['tool_choice' => 'required'] : [];
}
```

On the turn after the tool result, the package switches a forced `tool_choice` back to `auto`. Otherwise the model would keep calling the tool until it hit the step limit and never return text. A `tool_choice` of `none` is left as it is.

## Provider tools are not supported

Laravel AI provider tools, such as `WebSearch`, run inside a provider's own API, and Workers AI has no such tools. On `laravel/ai` 1.1 and later, Laravel AI removes them before the call, so the model answers without them and you get no error. On 0.9 to 1.0, the package throws `RuntimeException` with the message `Workers AI does not support [ToolName] provider tools.`

For web search, use [`CloudflareWebSearch`](/docs/guides/web-search/). For anything else, write a normal tool that calls the service yourself.

## Limit the steps

Laravel AI runs the tool loop, so you cap the number of steps the usual way, with `#[MaxSteps]` on the agent.

Source: https://laravel-cf-workersai.meirdick.com/docs/guides/tools/index.mdx
