# Quick Start

## Installation

```bash
composer require janschuri/eloquent-ai-tools
```

## Requirements

- PHP `^8.3`
- Laravel `^13.0`
- Laravel AI SDK (`laravel/ai`) `^0.10`

## Minimal Example

```php
<?php

use EloquentAiTools\Concerns\HasToolModel;
use EloquentAiTools\Decision;
use EloquentAiTools\ToolBuilder;
use Illuminate\Database\Eloquent\Model;
use Laravel\Ai\Tools\Request;

class Article extends Model
{
    use HasToolModel;

    public static function toolConfig()
    {
        return static::newToolConfig([
            'title' => 'Article headline',
            'status' => 'Publication status',
            'views' => 'View count',
            'published_at' => 'Publish date',
        ])
            ->label('Articles')
            ->modelDescription('Articles from the CMS.')
            ->allowRead()
            ->maxLimit(50)
            ->whereMaxDepth(3)
            ->whereMaxConditionsPerGroup(10)
            ->scopes([
                'published' => 'Only published articles.',
            ])
            ->reading(function (Request $request, array $appliers) {
                return Decision::accept();
            });
    }
}

$tools = ToolBuilder::make()
    ->add(Article::toolConfig())
    ->build();
```

That exposes a `read_articles` tool. Its schema and description are generated from the `Article` config plus the active query resolvers, so the tool stays aligned with the model instead of becoming a second thing to maintain.

If you need a more specific or collision-resistant name, add a tool key:

```php
->toolKey('cms')
```

That changes the tool name to `read_cms_articles`.

`ToolBuilder` currently emits read tools only, so `allowRead()` is the switch that actually makes the model available.

## Supported Query Features

Out of the box, the read tool supports:

- a required `explain` field for intent
- optional reusable numeric `expressions`
- a required `select` list
- a required `distinct` flag
- typed `where` filters, including nested condition groups and relation existence checks
- `groupBy`
- `orderBy`
- `limit` and `offset`
- auto-derived relation joins for supported dotted relation paths
- Eloquent scopes, so you can keep using Laravel's native way to restrict model queries
- scoped eager loading for configured relations, including nested `with` paths
- scoped direct relation aggregates through `withAggregate`
- an optional per-model read policy callback

## Next Reading

- [Tool Configuration](./Tool-Configuration.md) for every builder option and default
- [Query Reference](./Query-Reference.md) for the exact request shape
- [Relation Paths And Scopes](./Relation-Paths-And-Scopes.md) for nested relations and dotted columns