Responses And Errors

Responses And Errors

Successful reads return JSON with a stable top-level shape:

{
  "total_count": 42,
  "returned_count": 10,
  "max_results": 10,
  "offset": 0,
  "items": []
}

Success Response Fields

• total_count: total matching rows or groups before pagination
• returned_count: number of items actually returned in this page
• max_results: the active limit used for this request
• offset: the active offset used for this request
• items: the selected rows, grouped rows, or aggregate summary row

For distinct queries without grouping, the tool counts the distinct projected rows rather than just counting root primary keys.

For whole-result aggregate queries without groupBy, total_count is 1.

Validation Errors

If request parsing or validation fails, the tool returns:

{
  "errors": [
    "..."
  ]
}

The runtime can report multiple validation errors in one response.

Denials And Approvals

If reading() denies a request, the tool returns:

{
  "error": "Request denied."
}

or the custom denial reason you provided.

If reading() returns Decision::approve(...), the tool uses Laravel AI's normal approval flow before the query is allowed to run.

Database Errors

If the query reaches the database and fails there, the tool returns a cleaned message shaped like:

{
  "error": "Database error: ..."
}

The implementation trims the SQLSTATE wrapper and adds a hint to check value formats, especially for typed columns such as dates.