Quick Start

Quick Start

Installation

composer require janschuri/eloquent-ai-tools

Requirements

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

Minimal Example

<?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:

->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 for every builder option and default
• Query Reference for the exact request shape
• Relation Paths And Scopes for nested relations and dotted columns