agent with tools

Fill {{SCENARIO}} and {{DOMAIN}}, copy, paste into your coding agent.

# Kickoff — Agent With Tools

Paste everything below into your coding agent after filling {{SCENARIO}} and {{DOMAIN}}.

---

You are working in this repo: Next.js 16 App Router + TypeScript + Tailwind, Clerk auth
(wired), Drizzle + Neon Postgres (schema `perficient`, `runs` table exists), Anthropic SDK
with `ANTHROPIC_API_KEY` in env. Deployed on Vercel; keep it deployable.

Build a tool-calling agent for this scenario: {{SCENARIO}} (domain: {{DOMAIN}}).

## Order of work

1. **Synthetic operational data.** Script seeds 3-4 domain tables in the `perficient`
   schema (e.g. for ops: work_orders, machines, technicians — adapt to {{DOMAIN}}), 30-60
   rows each via one Claude generation call, realistic and cross-referenced (foreign keys
   that actually join).
2. **Tools, read-only first.** 4-6 typed tools in `lib/tools.ts`, each a zod-validated
   function over Drizzle queries: `query_<entity>` (filterable list), `get_<entity>_detail`,
   one `aggregate_<metric>` (the agent must COMPUTE something, not just fetch). Tools are
   scoped to the signed-in Clerk userId where relevant. Every tool returns compact JSON.
3. **The loop.** `app/api/agent/route.ts`: Anthropic tool-use loop (model
   `claude-sonnet-4-6`) — max 8 iterations, accumulate token usage across rounds, log the
   full tool trace to `runs` (archetype "agent"). System prompt rules that matter:
   - Every figure in the answer must come from a tool result in THIS turn.
   - Verify computed answers with a second tool call when cheap ("do the parts sum to the whole?").
   - If the budget runs out, say the answer is partial — never fake completeness.
4. **UI** at `/app`: chat with the agent, and render the TOOL TRACE inline (which tool,
   what args, result row-count, latency). The visible trace is the demo — it proves the AI
   is reasoning over real data, not fetching-and-displaying.
5. **One write tool, gated.** Add a single mutating tool (e.g. create a work order) that
   requires an explicit user confirmation click before executing. Narrate: reads are free,
   writes need human sign-off.
6. **Mini eval.** 5 question→expected-tool assertions (right tool called AND succeeded,
   forbidden tools not called). Deterministic — no LLM judge needed for tool behavior.

## Constraints
- Milestone after each step. Errors: tool failures return `is_error` to the model, never
  crash the loop; cap iterations; timeout per tool.
- All model calls through `lib/ai.ts`; log usage on every run.