# AI Data Agent — Tool Catalog

Companion to **The AI Data Agent: Connecting Orders, Customers, Products and Inventory**.

Store intelligence (post 6) is analytics Q&A. This agent **joins entities** and returns **evidence**. Do **not** grant unrestricted database access.

```text
Business Question
  → AI Data Agent
  → Controlled Business Tools
  → Orders / Customers / Products / Inventory
  → Reasoning
  → Answer + Evidence
```

## Allowed tools (read)

| Tool | Returns | Must include | Must not |
| ---- | ------- | ------------ | -------- |
| `getOrder` | Order header + lines | `order_id`, `status`, `asOf` | Payment PAN, full address unless role |
| `getCustomer` | Account summary | `customer_id`, duplicate_flag | Password, payment methods |
| `getProduct` | Parent/child record | `sku`, `parent_id`, required attrs | Supplier cost unless finance role |
| `getInventory` | ATP | `sku`, `location`, `asOf` | Other warehouses the role cannot see |
| `listReturnsForOrder` | RMAs | `rma_id`, `reason_code` | Fraud labels as facts |
| `searchOrdersByCustomer` | Order ids | Pagination cap | Full PII dump |

Every answer field that is a fact must set `evidence_tool` + `evidence_ref`. If a join fails, return `unknown` — do not invent.

## Permissions

| Audience JWT | Tools |
| ------------ | ----- |
| Shopper | `getOrder` for **their** order only |
| Associate | Order + customer + inventory reads |
| Finance | + cost fields if a named tool exists |
| Agent runtime | Same as the **caller** role — never a superuser |

## Validation

- Cap result rows (example: 25)
- Reject tools that accept raw SQL
- Log tool name, args hash, latency on Gateway

## Related

- Analytics tools (post 6): [`analytics-tool-catalog.md`](analytics-tool-catalog.md)
- Data layer: [`ai-ready-business-data-layer.md`](ai-ready-business-data-layer.md)
- Security: [`ecommerce-agent-security-checklist.md`](ecommerce-agent-security-checklist.md)