> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zappway.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools API

> Internal reference for the Tools API — HTTP tool configuration, web page summary, YouTube summary tools, and agent tool management.

> **Internal documentation for developers.** This page covers the Tools API: tool CRUD, HTTP tool configuration, and built-in AI tool types. Not intended for end users.

***

## Route Map

| Method  | Endpoint                          | Handler File                          | Description               |
| ------- | --------------------------------- | ------------------------------------- | ------------------------- |
| `GET`   | `/api/tools/http-tool`            | `tools/http-tool/route.ts`            | HTTP tool config/test     |
| `POST`  | `/api/tools/http-tool`            | `tools/http-tool/route.ts`            | Create HTTP tool          |
| `GET`   | `/api/tools/web-page-summary`     | `tools/web-page-summary/route.ts`     | Web page summary tool     |
| `POST`  | `/api/tools/web-page-summary`     | `tools/web-page-summary/route.ts`     | Summarize a URL           |
| `GET`   | `/api/tools/youtube-summary`      | `tools/youtube-summary/route.ts`      | YouTube summary tool      |
| `POST`  | `/api/tools/youtube-summary`      | `tools/youtube-summary/route.ts`      | Summarize a YouTube video |
| `GET`   | `/api/agents/[id]/tools`          | `agents/[id]/tools/route.ts`          | List tools for an agent   |
| `PATCH` | `/api/agents/[id]/tools/[toolId]` | `agents/[id]/tools/[toolId]/route.ts` | Update tool config        |

***

## Tool Types

| Tool Type          | Description                         | Stored as                        |
| ------------------ | ----------------------------------- | -------------------------------- |
| `http`             | Custom HTTP request tool (API call) | `config: HttpToolConfig`         |
| `agent`            | Sub-agent delegation (specialist)   | `config: { targetAgentId, ... }` |
| `web_page_summary` | Summarize content from a URL        | Built-in, no config              |
| `youtube_summary`  | Summarize a YouTube video           | Built-in, no config              |

***

## HTTP Tool Config Schema

```ts theme={null}
interface HttpToolConfig {
  url: string;                    // Target URL
  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
  headers?: Record<string, string>;
  body?: string;                  // Template with {{variables}}
  auth?: {
    type: 'bearer' | 'basic' | 'api-key';
    value: string;
    headerName?: string;          // for api-key type
  };
  responseMapping?: {
    path: string;                 // JSONPath expression
    as: string;                   // Variable name for AI
  };
  timeout?: number;               // ms, default 30000
}
```

***

## Tool Config Storage

All tool configurations are stored as `Prisma.InputJsonObject` in the `Tool.config` column. When reading, cast appropriately:

```ts theme={null}
const config = tool.config as HttpToolConfig | null;
```

***

## Web Page Summary

The `web-page-summary` tool fetches a URL and uses AI to summarize its content. Key implementation notes:

* `GET /api/tools/web-page-summary` returns the latest three `LLMTaskOutput` rows where `type = web_page_summary`.
* `POST /api/tools/web-page-summary` requires the `api-key` header to match `NEXTAUTH_SECRET`.
* Request payload is validated with `WebPageSummarySchema` and includes `url` plus optional `date`.
* Page HTML is loaded through `loadPageContent`, stripped with Cheerio, chunked with `splitTextByToken`, and summarized with `ChatModel`.
* Chunk sizing uses `ModelConfig[modelName].contextWindowTokens * 0.5`; keep catalog context sizing on `contextWindowTokens`.
* JSON output requests use the OpenAI SDK `response_format` type carried by `CallInput`.
* Returns a persisted `LLMTaskOutput` payload with metadata, summary sections, and FAQ data.

Example:

```bash theme={null}
curl -X POST "$APP_URL/api/tools/web-page-summary" \
  -H "api-key: $NEXTAUTH_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/article"}'
```

***

## YouTube Summary

The `youtube-summary` tool extracts video transcripts and summarizes them:

* `GET /api/tools/youtube-summary` returns the latest three `LLMTaskOutput` rows where `type = youtube_summary`.
* `POST /api/tools/youtube-summary` is implemented in `tools/youtube-summary/functions.ts` and exposed by the route module.
* Request payload is validated with `YoutubeSummarySchema`; do not cast parsed payloads to `any`.
* Unauthenticated requests are rate limited with `heavyRateLimiter`; authenticated internal calls use the `api-key` header.
* Transcript chunks are sized from `ModelConfig[summaryModel].contextWindowTokens * 0.5`.
* Model calls are typed as `Omit<CallInput, 'model'>` before the concrete model name is attached.
* Chapter extraction uses the `youtube_summary` OpenAI tool schema; normal summaries and FAQs use direct `ChatModel` calls.
* Returns or upserts a persisted `LLMTaskOutput` with localized transcript, chapters, summary, and FAQ fields depending on options.

Example:

```bash theme={null}
curl -X POST "$APP_URL/api/tools/youtube-summary" \
  -H "api-key: $NEXTAUTH_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.youtube.com/watch?v=VIDEO_ID","options":{"summarize":true,"extractChapters":true}}'
```

***

## Agent Tool Management

When an agent has tools:

```ts theme={null}
// GET /api/agents/[id]/tools
// Returns all tools for the agent (including type='agent' specialists)
// authMode: 'lightweight'

// PATCH /api/agents/[id]/tools/[toolId]
// Body: partial HttpToolConfig (or other tool-specific config)
// Merges with existing config using spread
```

***

## Known Issues / Gotchas

* **HTTP tool secret exposure:** The `auth.value` field stores API keys/tokens. Never return these in `GET` responses — mask with `***` or omit. Only set new values via `PATCH`.
* **HTTP tool injection risk:** The `url` and `body` fields support template variables. Validate that variable substitution cannot be used for SSRF (block internal IP ranges: `10.x`, `172.16-31.x`, `192.168.x`, `127.x`, `169.254.x`).
* **Specialist tools** (`type: 'agent'`) use the same `Tool` table but have completely different `config` structure from HTTP tools. Always check `tool.type` before reading `config`.