# Tools

Tools are individual service calls that the AI can invoke to fetch or generate data. Each tool maps to one downstream API endpoint or operation.

For **compositions** of multiple tools into a single aggregated result, see `../skills/`.

## Structure

Each domain has its own directory:

```
tools/
  account/
    definitions.ts   ← ToolDefinition[] for all account tools
    handlers.ts      ← ToolHandler functions (one per tool)
    index.ts         ← barrel export
  royalties/
  moneyhub/
  ...
```

## Adding a New Tool

1. **Pick the domain directory** (or create a new one if it doesn't fit any existing domain).

2. **Add the definition** to `definitions.ts`:

   ```ts
   {
     name: "get_something",             // snake_case, verb_noun pattern
     description: "...",                 // 1-3 sentences: what it returns, when to use it
     inputSchema: { ... },              // JSON Schema for tool inputs
     domain: "your_domain",             // must be in the ToolDomain union (types/ai.ts)
     label: "Fetching something",       // shown in the UI while executing
     hint: "Short discovery hint.",      // used by the search_tools catalog
     examples: [{ label, input }],      // helps the AI and the catalog search
     source: { type: "account" },       // optional: "View in app" link config
     // core: true,                     // omit (deferred by default) unless this tool
                                        // must be available on every round
   }
   ```

3. **Add the handler** to `handlers.ts`:

   ```ts
   const handleGetSomething: ToolHandler = async (input, headers) => {
     const result = await safeGet(
       `${serviceUrls.myService}/endpoint`,
       headers,
       {
         id: input["id"],
       },
     );
     return { data: result.data, error: result.error };
   };
   ```

4. **Export** from the domain's `index.ts`.

5. **Register** in `tools/definitions.ts` (barrel) and `tools/registry.ts` (handler map).

6. If you added a new domain, add it to the `ToolDomain` union in `types/ai.ts`.

## Conventions

- **Read-only by default.** Tools use GET endpoints and dataloader POSTs (bulk reads). No destructive operations.
- **Auth forwarding.** The user's JWT and identity headers are forwarded to downstream services. Never elevate privileges.
- **Error sanitization.** Never expose internal URLs, stack traces, or token details. Use `safeGet`/`safePost` which handle this.
- **Deferred by default.** Only set `core: true` if the tool must be available every round (search primitives, skill tools, file generation). Most tools should be deferred and discoverable via `search_tools`.
- **Descriptions are for the AI.** Keep them concise. Don't repeat rules that are in the system prompt. Don't add "do not use when..." disclaimers — let the AI reason.
- **Hints are for the catalog.** One sentence that helps `search_tools` find this tool by keyword.