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

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

- name: tags
  type: array
  required: false
  description: Labels to attach to the ticket.
  items:
    type: string

Nested object fields

- 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

auth:
  type: bearer
  env: ZENDESK_API_TOKEN

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

api_key

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

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

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

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:

svantic forge tool --validate my-spec.yaml

Programmatic validation:

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);
}

​Tool Spec Format Reference

​Complete Annotated Example

​Top-Level Fields

​Tool Definition

​When to use params vs body

​Field Definition

​Array fields

​Nested object fields

​Auth Configuration

​bearer

​api_key

​basic

​oauth2

​none

​Trigger Definitions

​webhook

​schedule

​emit

​queue

​file

​Validation