Home

EloquentAiTools Wiki

EloquentAiTools turns Eloquent models into safe, structured AI tools without introducing a parallel query language or a hand-maintained schema layer.

Instead of letting an agent invent SQL or forcing you to wrap every model in custom tool classes, the package builds a read-only AI query tool from the model config, schema, scopes, casts, and relations you already have.

Start Here

• Quick Start
• Tool Configuration
• Query Reference
• Query Model
• Relation Paths And Scopes
• Policies And Approvals
• Exposed Surface
• Responses And Errors
• Caching
• Roadmap

What You Get

The package currently focuses on:

• fitting directly into an existing Eloquent codebase instead of introducing a separate query layer
• turning Eloquent models into small, read-only AI query tools
• keeping relations and scopes explicit while deriving column types from the live model schema
• supporting the query features an AI usually needs: filtering, reusable numeric expressions, projection, distinct, grouping, sorting, pagination, eager loading, auto-derived relation joins, and relation aggregates
• reusing the same Eloquent scopes, relations, and casts you already rely on in the rest of the app
• supporting optional per-model read policy callbacks
• freezing multiple model configs together so relation-aware tools can be built safely

Important Notes

• ToolBuilder currently builds read tools only. A model must opt in with allowRead().
• Field descriptions improve tool descriptions, but they are not the runtime column allowlist. The runtime column set comes from the model's visible database columns after visible and hidden filtering.
• Relation-aware features only work when the related model is also registered in the same ToolBuilder registry.