# Responses And Errors

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

```json
{
  "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:

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

The runtime can report multiple validation errors in one response.

## Denials And Approvals

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

```json
{
  "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:

```json
{
  "error": "Database error: ..."
}
```

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