---
url: /guide/getting-started.md
---
# Getting Started

The toolkit is a community catalog of reusable AI tools for the [Laravel AI SDK](https://github.com/laravel/ai). The
tools are developed in one monorepo and split into small, independently installable packages.

A tool is a class implementing `Laravel\Ai\Contracts\Tool`:

```php
interface Tool
{
    public function description(): Stringable|string;
    public function handle(Request $request): Stringable|string;
    public function schema(JsonSchema $schema): array;
}
```

## Installation

Each tool is its own package. Require only the ones you need:

```bash
composer require shipfastlabs/toolkit-calculator
composer require shipfastlabs/toolkit-database
```

### Requirements

* PHP 8.4+
* [`laravel/ai`](https://github.com/laravel/ai)

### Configuration

Tools do not ship their own config files. Configurable tools read from the `ai.toolkit.<tool>` key of the Laravel AI
SDK's existing `config/ai.php`, which you add manually. See each tool's page for the exact keys. Pure tools such as
the Calculator need no configuration.

## Usage

Instantiate a tool and pass it to an agent's `tools()`:

```php
use Shipfastlabs\Toolkit\Calculator\CalculatorTool;
use Shipfastlabs\Toolkit\Database\DatabaseQueryTool;

$tools = [
    new CalculatorTool,
    new DatabaseQueryTool,
];
```

Each tool advertises its purpose via `description()` and its inputs via `schema()`; the model decides when to call it.
Tools return their result (or a friendly error message) as a string, so the model can react and recover.

Browse the [Tools](/tools/calculator) section for the full catalog. Each page is generated from that tool's README,
so the docs and the package always agree.

---

---
url: /guide/contributing.md
---
# Contributing

Tools are added to the [monorepo](https://github.com/shipfastlabs/toolkit), never to the read-only mirror packages.

1. Copy `stub/` to `src/<YourTool>/` and rename the class, namespace and `composer.json` package.
2. Implement `description()`, `schema()` and `handle()`; read any config from `ai.toolkit.<tool>` (tools ship no config files).
3. Generate the README scaffold: `tools/docgen.sh <YourTool>`.
4. Add the tool's autoload entries to the root `composer.json`, then `composer dump-autoload && composer test` until green (PHPStan max, 100% type + code coverage).
5. Open a PR. A maintainer applies `new-tool` and/or `release:patch|minor|major`.

After merge, a maintainer runs `composer publish` locally to create the mirror, split the folder, tag it and publish
to Packagist. See the full [CONTRIBUTING guide](https://github.com/shipfastlabs/toolkit/blob/main/CONTRIBUTING.md).

---

---
url: /tools/calculator.md
---
# Calculator

> Calculator tool for the Laravel AI SDK

Part of the [shipfastlabs/toolkit](https://github.com/shipfastlabs/toolkit) catalog of reusable AI tools for the Laravel AI SDK.

## Installation

```bash
composer require shipfastlabs/toolkit-calculator
```

## Usage

Instantiate the tool and pass it to an agent's `tools()`:

```php
use Shipfastlabs\Toolkit\Calculator\CalculatorTool;

$tools = [new CalculatorTool];
```

## Input schema

| Parameter | Type | Required | Description |
|---|---|---|---|
| `expression` | string | yes | The mathematical expression to evaluate, e.g. `"3 * (4 + 1)"`. |

Supports `+`, `-`, `*`, `/`, `%`, `^` (exponent, right-associative), parentheses, unary `+`/`-` and decimal numbers.

## Configuration

None. The calculator is pure and ships no config or service provider.

## Safety

The expression is parsed by a small recursive-descent evaluator; PHP's `eval()` is never used. Invalid input, division or modulo by zero, and non-finite results are returned to the model as plain strings rather than thrown, so the model can recover.

---

---
url: /tools/database.md
---
# Database

> Read-only database query tool for the Laravel AI SDK

Part of the [shipfastlabs/toolkit](https://github.com/shipfastlabs/toolkit) catalog of reusable AI tools for the Laravel AI SDK.

## Installation

```bash
composer require shipfastlabs/toolkit-database
```

## Usage

Instantiate the tool and pass it to an agent's `tools()`:

```php
use Shipfastlabs\Toolkit\Database\DatabaseQueryTool;

$tools = [new DatabaseQueryTool];
```

## Input schema

| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | A single read-only SQL `SELECT` statement. |

Matching rows are returned as pretty-printed JSON.

## Configuration

This tool ships no config file or service provider. It reads its settings from the `ai.toolkit.database` key of the
Laravel AI SDK's existing `config/ai.php`. Add the section manually:

```php
// config/ai.php

return [

    // ... existing laravel/ai config ...

    'toolkit' => [
        'database' => [
            'connection' => env('TOOLKIT_DATABASE_CONNECTION'),
            'max_rows' => (int) env('TOOLKIT_DATABASE_MAX_ROWS', 100),
        ],
    ],

];
```

| Key | Default | Description |
|---|---|---|
| `ai.toolkit.database.connection` | `null` (default connection) | The connection to query. Point at a read-only replica for extra safety. |
| `ai.toolkit.database.max_rows` | `100` | A `LIMIT` of this size is appended to any query that lacks one. |

## Safety

* **Read-only enforced**: only a single statement beginning with `SELECT` (or a `WITH … SELECT` CTE) is allowed.
* **Write keywords rejected**: `INSERT`, `UPDATE`, `DELETE`, `DROP`, `ALTER` and similar keywords are refused, even inside an otherwise-`SELECT` statement.
* **Single statement only**: queries containing `;` separators are refused.
* **Row cap**: results are bounded by `max_rows`.
* Query failures are returned to the model as strings, not thrown.

---

---
url: /tools/exa.md
---
# Exa

> Exa tools for the Laravel AI SDK - Search, Find Similar, Get Contents, and Answer

Part of the [shipfastlabs/toolkit](https://github.com/shipfastlabs/toolkit) catalog of reusable AI tools for the Laravel AI SDK.

## Installation

```bash
composer require shipfastlabs/toolkit-exa
```

## Usage

Register every Exa tool at once with the `Exa` helper:

```php
use Shipfastlabs\Toolkit\Exa\Exa;

$tools = Exa::all(); // Collection<int, Tool>
```

Or add individual tools to an agent's `tools()`:

```php
use Shipfastlabs\Toolkit\Exa\ExaSearch;
use Shipfastlabs\Toolkit\Exa\ExaFindSimilar;
use Shipfastlabs\Toolkit\Exa\ExaGetContents;
use Shipfastlabs\Toolkit\Exa\ExaAnswer;

$tools = [
    new ExaSearch,
    new ExaFindSimilar,
    new ExaGetContents,
    new ExaAnswer,
];
```

## Tools

### ExaSearch

Search the web with Exa's embeddings-based search engine.

| Parameter         | Type    | Required | Description                                                                 |
|-------------------|---------|----------|-----------------------------------------------------------------------------|
| `query`           | string  | yes      | The search query to look up on the web.                                     |
| `type`            | string  | no       | `"auto"`, `"keyword"`, `"neural"`, `"fast"`, or `"deep"`. Defaults to `"auto"`. |
| `num_results`     | integer | no       | Number of results to return (1-25). Defaults to 10.                         |
| `category`        | string  | no       | Focus a category, e.g. `"research paper"`, `"news"`, `"github"`, `"pdf"`.   |
| `include_domains` | string  | no       | Comma-separated domains to restrict results to.                            |
| `exclude_domains` | string  | no       | Comma-separated domains to exclude from results.                           |
| `include_text`    | boolean | no       | Whether to include each result's full page text. Defaults to true.          |

### ExaFindSimilar

Find pages semantically similar to a given URL.

| Parameter         | Type    | Required | Description                                                                 |
|-------------------|---------|----------|-----------------------------------------------------------------------------|
| `url`             | string  | yes      | The URL to find similar pages for.                                          |
| `num_results`     | integer | no       | Number of similar results to return (1-25). Defaults to 10.                 |
| `include_domains` | string  | no       | Comma-separated domains to restrict results to.                            |
| `exclude_domains` | string  | no       | Comma-separated domains to exclude from results.                           |
| `include_text`    | boolean | no       | Whether to include each result's full page text. Defaults to true.          |

### ExaGetContents

Retrieve clean, parsed contents from one or more URLs.

| Parameter    | Type    | Required | Description                                                                     |
|--------------|---------|----------|---------------------------------------------------------------------------------|
| `urls`       | string  | yes      | A single URL or comma-separated URLs (max 20) to fetch contents from.           |
| `text`       | boolean | no       | Whether to include the full page text. Defaults to true.                        |
| `summary`    | boolean | no       | Whether to include an AI-generated summary of each page. Defaults to false.     |
| `highlights` | boolean | no       | Whether to include relevant highlighted snippets. Defaults to false.            |
| `livecrawl`  | string  | no       | `"never"`, `"fallback"`, `"always"`, or `"preferred"`. Defaults to `"fallback"`. |

### ExaAnswer

Get a direct, sourced answer to a question with citations.

| Parameter      | Type    | Required | Description                                                              |
|----------------|---------|----------|--------------------------------------------------------------------------|
| `query`        | string  | yes      | The question to answer using web sources.                                |
| `include_text` | boolean | no       | Whether to include the full text of each cited source. Defaults to false. |

## Provider setup

All tools read their API credentials from Laravel's `services` config and their optional defaults from the `ai` config.

### 1. Add the Exa service to `config/services.php`

```php
// config/services.php

return [

    // ... existing services ...

    'exa' => [
        'key' => env('EXA_API_KEY'),
    ],

];
```

### 2. Add toolkit defaults to `config/ai.php`

```php
// config/ai.php

return [

    // ... existing laravel/ai config ...

    'toolkit' => [
        'exa' => [
            'search' => [
                'num_results' => (int) env('EXA_SEARCH_NUM_RESULTS', 10),
                'type' => env('EXA_SEARCH_TYPE', 'auto'),
                'include_text' => (bool) env('EXA_SEARCH_INCLUDE_TEXT', true),
            ],
            'find_similar' => [
                'num_results' => (int) env('EXA_FIND_SIMILAR_NUM_RESULTS', 10),
                'include_text' => (bool) env('EXA_FIND_SIMILAR_INCLUDE_TEXT', true),
            ],
            'contents' => [
                'text' => (bool) env('EXA_CONTENTS_TEXT', true),
                'livecrawl' => env('EXA_CONTENTS_LIVECRAWL', 'fallback'),
            ],
            'answer' => [
                'include_text' => (bool) env('EXA_ANSWER_INCLUDE_TEXT', false),
            ],
        ],
    ],

];
```

### 3. Add environment variables to `.env`

```dotenv
EXA_API_KEY=your-key-here

# Search defaults
EXA_SEARCH_NUM_RESULTS=10
EXA_SEARCH_TYPE=auto
EXA_SEARCH_INCLUDE_TEXT=true

# Find similar defaults
EXA_FIND_SIMILAR_NUM_RESULTS=10
EXA_FIND_SIMILAR_INCLUDE_TEXT=true

# Contents defaults
EXA_CONTENTS_TEXT=true
EXA_CONTENTS_LIVECRAWL=fallback

# Answer defaults
EXA_ANSWER_INCLUDE_TEXT=false
```

| Config key | Env var | Default | Description |
|---|---|---|---|
| `services.exa.key` | `EXA_API_KEY` | - | **Required.** Your Exa API key. |
| `ai.toolkit.exa.search.num_results` | `EXA_SEARCH_NUM_RESULTS` | `10` | Default search results (1-25). |
| `ai.toolkit.exa.search.type` | `EXA_SEARCH_TYPE` | `"auto"` | `"auto"`, `"keyword"`, `"neural"`, `"fast"`, or `"deep"`. |
| `ai.toolkit.exa.search.include_text` | `EXA_SEARCH_INCLUDE_TEXT` | `true` | Include full page text in search results. |
| `ai.toolkit.exa.find_similar.num_results` | `EXA_FIND_SIMILAR_NUM_RESULTS` | `10` | Default similar results (1-25). |
| `ai.toolkit.exa.find_similar.include_text` | `EXA_FIND_SIMILAR_INCLUDE_TEXT` | `true` | Include full page text in similar results. |
| `ai.toolkit.exa.contents.text` | `EXA_CONTENTS_TEXT` | `true` | Include full page text in contents. |
| `ai.toolkit.exa.contents.livecrawl` | `EXA_CONTENTS_LIVECRAWL` | `"fallback"` | `"never"`, `"fallback"`, `"always"`, or `"preferred"`. |
| `ai.toolkit.exa.answer.include_text` | `EXA_ANSWER_INCLUDE_TEXT` | `false` | Include full text of cited sources. |

## Safety

* All tools validate required inputs before calling the API.
* Numeric parameters are clamped to their valid ranges; enums fall back to safe defaults.
* `ExaGetContents` accepts at most 20 URLs per request.
* API errors are caught and returned as friendly string messages.
* Requires a valid Exa API key.

## Exa API

These tools use the [Exa API](https://exa.ai). Exa offers a free tier to get started.

Full API reference:

* [Search Endpoint](https://exa.ai/docs/reference/search)
* [Find Similar Links Endpoint](https://exa.ai/docs/reference/find-similar-links)
* [Get Contents Endpoint](https://exa.ai/docs/reference/get-contents)
* [Answer Endpoint](https://exa.ai/docs/reference/answer)

---

---
url: /tools/jigsawstack.md
---
# Jigsawstack

> JigsawStack tools for the Laravel AI SDK - sentiment, summary, embedding, translation, web search, scraping, vision, audio, and validation

Part of the [shipfastlabs/toolkit](https://github.com/shipfastlabs/toolkit) catalog of reusable AI tools for the Laravel AI SDK.

## Installation

```bash
composer require shipfastlabs/toolkit-jigsawstack
```

## Usage

Register every JigsawStack tool at once with the `JigsawStack` helper:

```php
use Shipfastlabs\Toolkit\JigsawStack\JigsawStack;

$tools = JigsawStack::all(); // Collection<int, Tool>
```

Or add individual tools to an agent's `tools()`:

```php
use Shipfastlabs\Toolkit\JigsawStack\JigsawStackWebSearch;
use Shipfastlabs\Toolkit\JigsawStack\JigsawStackSummary;

$tools = [
    new JigsawStackWebSearch,
    new JigsawStackSummary,
];
```

## Tools

Each tool maps to a JigsawStack endpoint and returns the raw JSON response (pretty-printed) so the model can read every field.

### General

| Class | Endpoint | Required | Optional |
|---|---|---|---|
| `JigsawStackSentiment` | `POST /v1/ai/sentiment` | `text` | — |
| `JigsawStackSummary` | `POST /v1/ai/summary` | `text` | `type` (`text`|`points`), `max_points` |
| `JigsawStackEmbedding` | `POST /v1/embedding` | `text` | `type` (default `text`) |
| `JigsawStackPrediction` | `POST /v1/ai/prediction` | `dataset` (JSON array of `{date,value}`) | `steps` |
| `JigsawStackTextToSql` | `POST /v1/ai/sql` | `prompt` | `sql_schema`, `database` |

### Translation

| Class | Endpoint | Required | Optional |
|---|---|---|---|
| `JigsawStackTranslateText` | `POST /v1/ai/translate` | `text`, `target_language` | `current_language` |
| `JigsawStackTranslateImage` | `POST /v1/ai/translate/image` | `url`, `target_language` | — |

### Web

| Class | Endpoint | Required | Optional |
|---|---|---|---|
| `JigsawStackWebSearch` | `POST /v1/web/search` | `query` | `ai_overview`, `safe_search`, `max_results` |
| `JigsawStackAiScrape` | `POST /v1/ai/scrape` | `url`, `element_prompts` (comma-separated) | `root_element_selector` |
| `JigsawStackHtmlToAny` | `POST /v1/web/html_to_any` | `html` | `type` (`png`|`jpeg`|`webp`|`pdf`), `full_page` |
| `JigsawStackSearchSuggestions` | `GET /v1/web/search/suggest` | `query` | — |

### Vision

| Class | Endpoint | Required | Optional |
|---|---|---|---|
| `JigsawStackVocr` | `POST /v1/vocr` | `url` | `prompt` |
| `JigsawStackObjectDetection` | `POST /v1/object_detection` | `url` | `prompts` (comma-separated), `annotated_image` |

### Audio

| Class | Endpoint | Required | Optional |
|---|---|---|---|
| `JigsawStackSpeechToText` | `POST /v1/ai/transcribe` | `url` | `language`, `translate` |

### Validation

| Class | Endpoint | Required | Optional |
|---|---|---|---|
| `JigsawStackNsfwDetection` | `POST /v1/validate/nsfw` | `url` | — |
| `JigsawStackProfanityCheck` | `POST /v1/validate/profanity` | `text` | `censor_replacement` |
| `JigsawStackSpellCheck` | `POST /v1/validate/spell_check` | `text` | `language_code` |
| `JigsawStackSpamCheck` | `POST /v1/validate/spam_check` | `text` | — |

## Configuration

Every tool reads its API key from Laravel's `services` config.

### 1. Add the JigsawStack service to `config/services.php`

```php
// config/services.php

return [

    // ... existing services ...

    'jigsawstack' => [
        'key' => env('JIGSAWSTACK_API_KEY'),
    ],

];
```

### 2. Add the environment variable to `.env`

```dotenv
JIGSAWSTACK_API_KEY=your-key-here
```

| Config key | Env var | Default | Description |
|---|---|---|---|
| `services.jigsawstack.key` | `JIGSAWSTACK_API_KEY` | - | **Required.** Your JigsawStack API key, sent as the `x-api-key` header. |

## Safety

* All tools validate required inputs before calling the API.
* Requests time out after 60 seconds.
* API errors and network failures are caught and returned as friendly string messages so the model can recover.
* Requires a valid JigsawStack API key; tools return a clear "not configured" message when it is missing.

## JigsawStack API

These tools use the [JigsawStack API](https://jigsawstack.com/docs). See the [API reference](https://jigsawstack.com/docs/api-reference) for full details on each endpoint and its response shape.

---

---
url: /tools/perplexity.md
---
# Perplexity

> Perplexity tools for the Laravel AI SDK - Search and Ask (Sonar)

Part of the [shipfastlabs/toolkit](https://github.com/shipfastlabs/toolkit) catalog of reusable AI tools for the Laravel AI SDK.

## Installation

```bash
composer require shipfastlabs/toolkit-perplexity
```

## Usage

Register every Perplexity tool at once with the `Perplexity` helper:

```php
use Shipfastlabs\Toolkit\Perplexity\Perplexity;

$tools = Perplexity::all(); // Collection<int, Tool>
```

Or add individual tools to an agent's `tools()`:

```php
use Shipfastlabs\Toolkit\Perplexity\PerplexitySearch;
use Shipfastlabs\Toolkit\Perplexity\PerplexityAsk;

$tools = [
    new PerplexitySearch,
    new PerplexityAsk,
];
```

## Tools

### PerplexitySearch

Search the web for real-time information and get a ranked list of sources. Uses the [Perplexity Search API](https://docs.perplexity.ai/api-reference/search-post).

| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | The search query to look up on the web. |
| `max_results` | integer | no | Maximum number of results to return (1-20). Defaults to 10. |
| `search_recency_filter` | string | no | Restrict results to a recent window: `"hour"`, `"day"`, `"week"`, `"month"`, or `"year"`. No filter by default. |

### PerplexityAsk

Ask a question and get a direct, cited answer grounded in a live web search using Perplexity's [Sonar models](https://docs.perplexity.ai/api-reference/chat-completions-post). The response includes the answer text plus the `search_results` and `citations` used.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | The question to ask Perplexity. |
| `model` | string | no | Sonar model: `"sonar"`, `"sonar-pro"`, `"sonar-reasoning"`, `"sonar-reasoning-pro"`, or `"sonar-deep-research"`. Defaults to `"sonar"`. |
| `search_mode` | string | no | `"web"` for the open web, `"academic"` for scholarly sources, or `"sec"` for SEC filings. Defaults to `"web"`. |

## Provider setup

Both tools read their API key from Laravel's `services` config and their optional defaults from the `ai` config.

### 1. Add the Perplexity service to `config/services.php`

```php
// config/services.php

return [

    // ... existing services ...

    'perplexity' => [
        'key' => env('PERPLEXITY_API_KEY'),
    ],

];
```

### 2. Add toolkit defaults to `config/ai.php`

```php
// config/ai.php

return [

    // ... existing laravel/ai config ...

    'toolkit' => [
        'perplexity' => [
            'search' => [
                'max_results' => (int) env('PERPLEXITY_SEARCH_MAX_RESULTS', 10),
                'recency' => env('PERPLEXITY_SEARCH_RECENCY'),
            ],
            'ask' => [
                'model' => env('PERPLEXITY_ASK_MODEL', 'sonar'),
                'search_mode' => env('PERPLEXITY_ASK_SEARCH_MODE', 'web'),
            ],
        ],
    ],

];
```

### 3. Add environment variables to `.env`

```dotenv
PERPLEXITY_API_KEY=pplx-your-key-here

# Search defaults
PERPLEXITY_SEARCH_MAX_RESULTS=10
PERPLEXITY_SEARCH_RECENCY=

# Ask defaults
PERPLEXITY_ASK_MODEL=sonar
PERPLEXITY_ASK_SEARCH_MODE=web
```

| Config key | Env var | Default | Description |
|---|---|---|---|
| `services.perplexity.key` | `PERPLEXITY_API_KEY` | - | **Required.** Your Perplexity API key. |
| `ai.toolkit.perplexity.search.max_results` | `PERPLEXITY_SEARCH_MAX_RESULTS` | `10` | Default search results (1-20). |
| `ai.toolkit.perplexity.search.recency` | `PERPLEXITY_SEARCH_RECENCY` | - | Default recency filter (`hour`/`day`/`week`/`month`/`year`). |
| `ai.toolkit.perplexity.ask.model` | `PERPLEXITY_ASK_MODEL` | `"sonar"` | Default Sonar model. |
| `ai.toolkit.perplexity.ask.search_mode` | `PERPLEXITY_ASK_SEARCH_MODE` | `"web"` | Default search mode (`web`/`academic`/`sec`). |

## Safety

* Both tools validate required inputs before calling the API.
* `max_results` is clamped to its valid 1-20 range.
* `model`, `search_mode`, and `search_recency_filter` are validated against allow-lists, falling back to safe defaults.
* API errors are caught and returned as friendly string messages.
* Requires a valid Perplexity API key.

## Perplexity API

These tools use the [Perplexity API](https://docs.perplexity.ai). You'll need an API key from your [Perplexity account settings](https://www.perplexity.ai/account/api).

Full API reference:

* [Search Endpoint](https://docs.perplexity.ai/api-reference/search-post)
* [Chat Completions Endpoint](https://docs.perplexity.ai/api-reference/chat-completions-post)

---

---
url: /tools/tavily.md
---
# Tavily

> Tavily tools for the Laravel AI SDK - Search, Extract, Crawl, and Map

Part of the [shipfastlabs/toolkit](https://github.com/shipfastlabs/toolkit) catalog of reusable AI tools for the Laravel AI SDK.

## Installation

```bash
composer require shipfastlabs/toolkit-tavily
```

## Usage

Register every Tavily tool at once with the `Tavily` helper:

```php
use Shipfastlabs\Toolkit\Tavily\Tavily;

$tools = Tavily::all(); // Collection<int, Tool>
```

Or add individual tools to an agent's `tools()`:

```php
use Shipfastlabs\Toolkit\Tavily\TavilySearch;
use Shipfastlabs\Toolkit\Tavily\TavilyExtract;
use Shipfastlabs\Toolkit\Tavily\TavilyCrawl;
use Shipfastlabs\Toolkit\Tavily\TavilyMap;

$tools = [
    new TavilySearch,
    new TavilyExtract,
    new TavilyCrawl,
    new TavilyMap,
];
```

## Tools

### TavilySearch

Search the web for real-time information.

| Parameter     | Type    | Required | Description                                                        |
|---------------|---------|----------|--------------------------------------------------------------------|
| `query`       | string  | yes      | The search query to look up on the web.                            |
| `max_results` | integer | no       | Maximum number of search results to return (1-10). Defaults to 5.  |
| `search_depth` | string | no       | `"basic"` for fast results or `"advanced"` for comprehensive. Defaults to `"basic"`. |
| `include_answer` | boolean | no    | Whether to include a concise AI-generated answer. Defaults to false. |

### TavilyExtract

Extract clean, structured content from URLs.

| Parameter     | Type    | Required | Description                                                        |
|---------------|---------|----------|--------------------------------------------------------------------|
| `urls`        | string  | yes      | A single URL or comma-separated URLs to extract content from.       |
| `query`       | string  | no       | Optional query to rerank extracted chunks by relevance.            |
| `extract_depth` | string | no     | `"basic"` or `"advanced"`. Defaults to `"basic"`.                  |
| `format`      | string  | no       | `"markdown"` or `"text"`. Defaults to `"markdown"`.                |
| `include_images` | boolean | no    | Whether to include images extracted from URLs. Defaults to false.  |

### TavilyCrawl

Intelligently crawl a website and extract content.

| Parameter     | Type    | Required | Description                                                        |
|---------------|---------|----------|--------------------------------------------------------------------|
| `url`         | string  | yes      | The root URL to begin the crawl from.                              |
| `instructions` | string | no       | Optional natural language instructions for the crawler.            |
| `max_depth`   | integer | no       | Maximum crawl depth (1-5). Defaults to 1.                        |
| `max_breadth` | integer | no       | Maximum links to follow per page (1-500). Defaults to 20.         |
| `limit`       | integer | no       | Total number of links to process. Defaults to 50.                 |
| `extract_depth` | string | no     | `"basic"` or `"advanced"`. Defaults to `"basic"`.                  |
| `allow_external` | boolean | no    | Whether to allow crawling external domains. Defaults to false.      |

### TavilyMap

Discover and map a website's structure.

| Parameter     | Type    | Required | Description                                                        |
|---------------|---------|----------|--------------------------------------------------------------------|
| `url`         | string  | yes      | The root URL to begin the mapping from.                            |
| `instructions` | string | no       | Optional natural language instructions for the crawler.            |
| `max_depth`   | integer | no       | Maximum map depth (1-5). Defaults to 1.                            |
| `max_breadth` | integer | no       | Maximum links to follow per page (1-500). Defaults to 20.         |
| `limit`       | integer | no       | Total number of links to process. Defaults to 50.                 |
| `allow_external` | boolean | no    | Whether to allow crawling external domains. Defaults to false.      |

## Provider setup

All tools read their API credentials from Laravel's `services` config and their optional defaults from the `ai` config.

### 1. Add the Tavily service to `config/services.php`

```php
// config/services.php

return [

    // ... existing services ...

    'tavily' => [
        'key' => env('TAVILY_API_KEY'),
    ],

];
```

### 2. Add toolkit defaults to `config/ai.php`

```php
// config/ai.php

return [

    // ... existing laravel/ai config ...

    'toolkit' => [
        'tavily' => [
            'search' => [
                'max_results' => (int) env('TAVILY_SEARCH_MAX_RESULTS', 5),
                'search_depth' => env('TAVILY_SEARCH_DEPTH', 'basic'),
                'include_answer' => (bool) env('TAVILY_SEARCH_INCLUDE_ANSWER', false),
            ],
            'extract' => [
                'extract_depth' => env('TAVILY_EXTRACT_DEPTH', 'basic'),
                'format' => env('TAVILY_EXTRACT_FORMAT', 'markdown'),
            ],
            'crawl' => [
                'max_depth' => (int) env('TAVILY_CRAWL_MAX_DEPTH', 1),
                'max_breadth' => (int) env('TAVILY_CRAWL_MAX_BREADTH', 20),
                'limit' => (int) env('TAVILY_CRAWL_LIMIT', 50),
                'extract_depth' => env('TAVILY_CRAWL_EXTRACT_DEPTH', 'basic'),
            ],
            'map' => [
                'max_depth' => (int) env('TAVILY_MAP_MAX_DEPTH', 1),
                'max_breadth' => (int) env('TAVILY_MAP_MAX_BREADTH', 20),
                'limit' => (int) env('TAVILY_MAP_LIMIT', 50),
            ],
        ],
    ],

];
```

### 3. Add environment variables to `.env`

```dotenv
TAVILY_API_KEY=tvly-your-key-here

# Search defaults
TAVILY_SEARCH_MAX_RESULTS=5
TAVILY_SEARCH_DEPTH=basic
TAVILY_SEARCH_INCLUDE_ANSWER=false

# Extract defaults
TAVILY_EXTRACT_DEPTH=basic
TAVILY_EXTRACT_FORMAT=markdown

# Crawl defaults
TAVILY_CRAWL_MAX_DEPTH=1
TAVILY_CRAWL_MAX_BREADTH=20
TAVILY_CRAWL_LIMIT=50
TAVILY_CRAWL_EXTRACT_DEPTH=basic

# Map defaults
TAVILY_MAP_MAX_DEPTH=1
TAVILY_MAP_MAX_BREADTH=20
TAVILY_MAP_LIMIT=50
```

| Config key | Env var | Default | Description |
|---|---|---|---|
| `services.tavily.key` | `TAVILY_API_KEY` | - | **Required.** Your Tavily API key. |
| `ai.toolkit.tavily.search.max_results` | `TAVILY_SEARCH_MAX_RESULTS` | `5` | Default search results (1-10). |
| `ai.toolkit.tavily.search.search_depth` | `TAVILY_SEARCH_DEPTH` | `"basic"` | `"basic"` or `"advanced"`. |
| `ai.toolkit.tavily.search.include_answer` | `TAVILY_SEARCH_INCLUDE_ANSWER` | `false` | Default for AI-generated answer. |
| `ai.toolkit.tavily.extract.extract_depth` | `TAVILY_EXTRACT_DEPTH` | `"basic"` | `"basic"` or `"advanced"`. |
| `ai.toolkit.tavily.extract.format` | `TAVILY_EXTRACT_FORMAT` | `"markdown"` | `"markdown"` or `"text"`. |
| `ai.toolkit.tavily.crawl.max_depth` | `TAVILY_CRAWL_MAX_DEPTH` | `1` | Max crawl depth (1-5). |
| `ai.toolkit.tavily.crawl.max_breadth` | `TAVILY_CRAWL_MAX_BREADTH` | `20` | Max links per page (1-500). |
| `ai.toolkit.tavily.crawl.limit` | `TAVILY_CRAWL_LIMIT` | `50` | Total links to process. |
| `ai.toolkit.tavily.crawl.extract_depth` | `TAVILY_CRAWL_EXTRACT_DEPTH` | `"basic"` | `"basic"` or `"advanced"`. |
| `ai.toolkit.tavily.map.max_depth` | `TAVILY_MAP_MAX_DEPTH` | `1` | Max map depth (1-5). |
| `ai.toolkit.tavily.map.max_breadth` | `TAVILY_MAP_MAX_BREADTH` | `20` | Max links per page (1-500). |
| `ai.toolkit.tavily.map.limit` | `TAVILY_MAP_LIMIT` | `50` | Total links to process. |

## Safety

* All tools validate required inputs before calling the API.
* Numeric parameters are clamped to their valid ranges.
* API errors are caught and returned as friendly string messages.
* Requires a valid Tavily API key.

## Tavily API

These tools use the Tavily API. Tavily offers a generous free tier with 1,000 API credits per month.

Full API reference:

* [Search Endpoint](https://docs.tavily.com/documentation/api-reference/endpoint/search)
* [Extract Endpoint](https://docs.tavily.com/documentation/api-reference/endpoint/extract)
* [Crawl Endpoint](https://docs.tavily.com/documentation/api-reference/endpoint/crawl)
* [Map Endpoint](https://docs.tavily.com/documentation/api-reference/endpoint/map)