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

# Tool spec format

# Tool Spec Format Reference

The Tool Spec is the intermediate YAML format that sits between your source material and the generated TypeScript. Every generation path -- OpenAPI, natural language -- produces a Tool Spec. You can also write one by hand.

Forge validates every Tool Spec against a Zod schema before generation. Invalid specs produce clear error messages pointing to the offending field.

## Complete Annotated Example

```yaml theme={null}
domain: zendesk
version: "1.0"
base_url: https://your-domain.zendesk.com

auth:
  type: bearer
  env: ZENDESK_API_TOKEN

tools:
  - name: create_ticket
    description: Create a new support ticket.
    method: POST
    path: /api/v2/tickets
    body:
      - name: subject
        type: string
        required: true
        description: The subject line of the ticket.
      - name: body
        type: string
        required: true
        description: The initial comment or description.
      - name: priority
        type: string
        required: false
        description: "Ticket priority: low, normal, high, or urgent."
        default: normal
        enum: [low, normal, high, urgent]
      - name: requester_email
        type: string
        required: false
        description: Email of the person filing the ticket.

  - name: list_tickets
    description: List tickets, optionally filtered by status.
    method: GET
    path: /api/v2/tickets
    params:
      - name: status
        type: string
        required: false
        description: "Filter by status: new, open, pending, solved, closed."
        enum: [new, open, pending, solved, closed]
      - name: page
        type: number
        required: false
        description: Page number for pagination.
        default: 1

  - name: get_ticket
    description: Get a single ticket by ID.
    method: GET
    path: /api/v2/tickets/{ticket_id}
    params:
      - name: ticket_id
        type: number
        required: true
        description: The ticket ID.

triggers:
  - type: webhook
    name: on_ticket_created
    description: Fires when a new ticket is created in Zendesk.
    path: /webhooks/zendesk/ticket-created
    event: ticket.created
    secret_env: ZENDESK_WEBHOOK_SECRET

  - type: schedule
    name: check_sla_breaches
    description: Check for SLA breaches every 15 minutes.
    cron: "*/15 * * * *"
```

## Top-Level Fields

| Field      | Type           | Required | Description                                                                                                        |
| ---------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `domain`   | `string`       | Yes      | Identifier for this tool set (e.g. `zendesk`, `billing`, `datadog`). Used for file naming and collision prefixing. |
| `version`  | `string`       | No       | Version of this tool spec. Informational only.                                                                     |
| `base_url` | `string`       | No       | Base URL for all HTTP tools. Can reference env vars: `${ZENDESK_BASE_URL}`.                                        |
| `auth`     | `AuthConfig`   | No       | Default auth configuration applied to all tools unless overridden.                                                 |
| `tools`    | `ToolDef[]`    | Yes      | Array of tool definitions.                                                                                         |
| `triggers` | `TriggerDef[]` | No       | Array of trigger definitions.                                                                                      |

## Tool Definition

Each entry in the `tools` array defines one agent capability.

| Field         | Type         | Required | Description                                                                     |
| ------------- | ------------ | -------- | ------------------------------------------------------------------------------- |
| `name`        | `string`     | Yes      | Unique identifier. Use `snake_case`.                                            |
| `description` | `string`     | Yes      | What this tool does. The LLM reads this.                                        |
| `method`      | `string`     | No       | HTTP method (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`). Omit for non-HTTP tools. |
| `path`        | `string`     | No       | URL path, relative to `base_url`. Use `{param}` for path parameters.            |
| `params`      | `FieldDef[]` | No       | Query parameters and path parameters.                                           |
| `body`        | `FieldDef[]` | No       | Request body fields.                                                            |
| `auth`        | `AuthConfig` | No       | Override the top-level auth for this specific tool.                             |

### When to use `params` vs `body`

* `params` -- fields sent as URL query parameters or interpolated into the path.
* `body` -- fields sent in the JSON request body.

For `GET` and `DELETE`, use `params`. For `POST`, `PUT`, and `PATCH`, use `body` for the payload and `params` for path/query parameters.

## Field Definition

Each entry in `params` or `body` is a `FieldDef`:

| Field         | Type         | Required | Description                                                          |
| ------------- | ------------ | -------- | -------------------------------------------------------------------- |
| `name`        | `string`     | Yes      | Field name.                                                          |
| `type`        | `string`     | Yes      | One of: `string`, `number`, `integer`, `boolean`, `array`, `object`. |
| `required`    | `boolean`    | No       | Whether this field is required. Default: `false`.                    |
| `description` | `string`     | Yes      | What this field represents. The LLM reads this.                      |
| `default`     | `any`        | No       | Default value if not provided.                                       |
| `enum`        | `string[]`   | No       | Allowed values (for `string` type).                                  |
| `items`       | `FieldDef`   | No       | Element definition for `array` type fields.                          |
| `properties`  | `FieldDef[]` | No       | Nested field definitions for `object` type fields.                   |

### Array fields

```yaml theme={null}
- name: tags
  type: array
  required: false
  description: Labels to attach to the ticket.
  items:
    type: string
```

### Nested object fields

```yaml theme={null}
- name: address
  type: object
  required: true
  description: The customer's shipping address.
  properties:
    - name: street
      type: string
      required: true
      description: Street address.
    - name: city
      type: string
      required: true
      description: City name.
    - name: zip
      type: string
      required: true
      description: Postal code.
```

## Auth Configuration

| Field    | Type     | Required | Description                                                        |
| -------- | -------- | -------- | ------------------------------------------------------------------ |
| `type`   | `string` | Yes      | One of: `bearer`, `api_key`, `basic`, `oauth2`, `none`.            |
| `env`    | `string` | No       | Environment variable name for the credential.                      |
| `header` | `string` | No       | Custom header name (for `api_key` type). Default: `Authorization`. |

### bearer

```yaml theme={null}
auth:
  type: bearer
  env: ZENDESK_API_TOKEN
```

Generated code adds `Authorization: Bearer ${process.env.ZENDESK_API_TOKEN}` to requests.

### api\_key

```yaml theme={null}
auth:
  type: api_key
  env: DATADOG_API_KEY
  header: DD-API-KEY
```

Generated code adds the custom header with the value from the env var.

### basic

```yaml theme={null}
auth:
  type: basic
  env: JIRA_USERNAME
```

Forge assumes a companion `JIRA_PASSWORD` env var (the `env` value with `_USERNAME` replaced by `_PASSWORD`). Generated code encodes them as `Basic base64(user:pass)`.

### oauth2

```yaml theme={null}
auth:
  type: oauth2
  env: SLACK_CLIENT_ID
```

Forge assumes companion env vars: `SLACK_CLIENT_SECRET`, `SLACK_TOKEN_URL`, `SLACK_REDIRECT_URI`. The generated code includes a token refresh flow.

### none

```yaml theme={null}
auth:
  type: none
```

No auth headers are added.

## Trigger Definitions

Triggers define how external events invoke agent capabilities.

### webhook

| Field         | Type        | Required | Description                                                  |
| ------------- | ----------- | -------- | ------------------------------------------------------------ |
| `type`        | `"webhook"` | Yes      |                                                              |
| `name`        | `string`    | Yes      | Trigger identifier.                                          |
| `description` | `string`    | Yes      | What this trigger does.                                      |
| `path`        | `string`    | Yes      | The HTTP path to register (e.g. `/webhooks/zendesk/ticket`). |
| `event`       | `string`    | No       | Event name for documentation/logging.                        |
| `secret_env`  | `string`    | No       | Env var holding the webhook signing secret for verification. |

### schedule

| Field         | Type         | Required | Description                              |
| ------------- | ------------ | -------- | ---------------------------------------- |
| `type`        | `"schedule"` | Yes      |                                          |
| `name`        | `string`     | Yes      | Trigger identifier.                      |
| `description` | `string`     | Yes      | What this trigger does.                  |
| `cron`        | `string`     | Yes      | Cron expression (e.g. `"*/15 * * * *"`). |

### emit

| Field         | Type     | Required | Description                                 |
| ------------- | -------- | -------- | ------------------------------------------- |
| `type`        | `"emit"` | Yes      |                                             |
| `name`        | `string` | Yes      | Trigger identifier.                         |
| `description` | `string` | Yes      | What this trigger does.                     |
| `event`       | `string` | Yes      | The event name to emit on the Svantic mesh. |

### queue

| Field         | Type      | Required | Description                              |
| ------------- | --------- | -------- | ---------------------------------------- |
| `type`        | `"queue"` | Yes      |                                          |
| `name`        | `string`  | Yes      | Trigger identifier.                      |
| `description` | `string`  | Yes      | What this trigger does.                  |
| `queue_url`   | `string`  | Yes      | SQS/Redis/RabbitMQ queue URL.            |
| `queue_env`   | `string`  | No       | Env var for the queue connection string. |

### file

| Field         | Type       | Required | Description                                                          |
| ------------- | ---------- | -------- | -------------------------------------------------------------------- |
| `type`        | `"file"`   | Yes      |                                                                      |
| `name`        | `string`   | Yes      | Trigger identifier.                                                  |
| `description` | `string`   | Yes      | What this trigger does.                                              |
| `watch_path`  | `string`   | Yes      | Directory or glob to watch for file changes.                         |
| `events`      | `string[]` | No       | File events to react to: `create`, `modify`, `delete`. Default: all. |

## Validation

Forge validates the Tool Spec against a Zod schema before generating code. Common validation errors:

```
Error: Tool spec validation failed:
  tools[0].name — Required
  tools[1].params[2].type — Invalid enum value. Expected 'string' | 'number' | ...
  auth.type — Invalid enum value. Expected 'bearer' | 'api_key' | ...
```

Validate a spec without generating:

```bash theme={null}
svantic forge tool --validate my-spec.yaml
```

Programmatic validation:

```typescript theme={null}
import { load_spec } from '@svantic/sdk/forge';

try {
  const spec = await load_spec('./my-spec.yaml');
  console.log('Valid:', spec.tools.length, 'tools');
} catch (err) {
  console.error(err.message);
}
```