Tool Configuration

Tool Configuration

HasToolModel::toolConfig() returns a ToolConfigBuilder for one Eloquent model. ToolBuilder freezes all registered builders into one resolved registry and then creates the actual tool instances.

What The Builder Controls

• label(string): human-readable label used in tool names and descriptions
• toolKey(string): extra name segment to avoid collisions, for example read_cms_articles
• modelDescription(string): free-text description added to the tool description
• allowRead(bool = true): opt in to generating the read tool for this model
• reading(callable): per-request policy callback returning Decision or bool

Limits And Defaults

The fluent builder defaults are stricter than the raw ToolConfig value object defaults:

• maxLimit(25) by default on ToolConfigBuilder
• maxOffset(10000) by default
• whereMaxDepth(3) by default
• whereMaxConditionsPerGroup(25) by default
• relationPathMaxDepth(5) by default

Important runtime defaults:

• request limit defaults to 10 when omitted
• request offset defaults to 0 when omitted

maxOffset(0) is a valid way to disallow paging past the first page.

Fields

The array passed into newToolConfig([...]), usually from inside your model's toolConfig() method, is a field-description map, not the actual runtime allowlist.

The runtime column set is derived from the live model schema:

• database columns are discovered from the model's table
• casts refine the detected data types
• enum columns expose their known enum values
• visible and hidden filter which columns are available

That means field descriptions improve the generated tool description, but the actual queryable columns come from the model schema snapshot.

Relations

relations([...]) is explicit opt-in for relation-aware features.

Configured relations drive:

• with
• withAggregate
• nested eager-load paths derived from related model configs
• dotted relation-path columns in where, select, groupBy, orderBy, and expressions where the relation kind supports them

Those dotted relation-path columns trigger join planning automatically. The current tool does not expose a user-specified top-level join request field.

Important constraint:

• if a related model is not also registered in the same ToolBuilder, the relation is dropped from the resolved schema and a warning is logged

Scopes

scopes([...]) exposes named local scopes the AI may apply.

Those scopes are applied:

• on the root query for the current model
• on related queries used for eager loading
• on related queries used for withAggregate
• on auto-derived relation-path joins where the related model contributes scoped columns

Read Policy Callback

reading(function (Request $request, array $appliers) { ... }) runs after the request has been parsed and validated into appliers.

It may return:

• Decision::accept() or true
• Decision::deny($reason) or false
• Decision::approve($reason)

If the callback returns anything else, the tool throws an InvalidArgumentException.