Co-locate tools under the route handler

As tools multiply, a flat lib/agent-tools.ts file becomes a pile. The fix is not a framework, it is a folder. Group each tool under lib/tools and expose them through one barrel file next to the route handler. The route handler stays a one-screen read forever.

src/app/api/chat/ and src/lib/tools/
bash
src/
  app/
    api/
      chat/
        route.ts         # POST handler, streamText, maxSteps
  lib/
    schemas.ts         # Zod request schema
    tools/
      index.ts         # barrel: exports agentTools map
      get-weather.ts   # one file per tool
      calculator.ts
      web-search.ts
      fetch-url.ts
    utils.ts           # SYSTEM_PROMPT + helpers

One file per tool keeps diffs small and PRs reviewable. The barrel file assembles the final tools map the route handler imports.

lib/tools/index.ts
typescript
import { getWeather } from './get-weather';
import { calculator } from './calculator';
import { webSearch } from './web-search';
import { fetchUrl } from './fetch-url';

export const agentTools = {
  get_weather: getWeather,
  calculator,
  web_search: webSearch,
  fetch_url: fetchUrl,
};

export type AgentToolName = keyof typeof agentTools;

The barrel is where you name tools. The keys here are the names the model sees. Keep them snake_case and short so the model picks the right one on the first try.

Ordering exercise: Order the request flow through the codebase

Loading practice…

Checkpoint: Tools and reasoning checkpoint

Loading practice…