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

# Tools

> Define an agent tool as config: its parameters, when it should fire, and how Roark grades and mocks it

A `tool` describes a function your agent can call: its name, the parameters it takes, when it should be invoked, and what a successful result looks like. Roark uses that description to **grade and mock** tool calls in simulations: it checks the agent reached for the right tool at the right moment with sensible arguments, and it stands in a mock result so the conversation can carry on. Scope a tool to one agent with `agent`, or omit it for a project-wide tool.

```typescript TypeScript theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
import { defineTool } from '@roarkanalytics/sdk/lib/config';

const bookAppointment = defineTool({
  name: 'book-appointment',
  description: 'Book a slot in the scheduling system',
  agent: 'frontdesk', // scope to one agent by name; omit for a project-wide tool
  parameters: {
    date: 'string',
    time: 'string',
    partySize: 'number',
  },
  invocationCriteria: 'Call once the caller has confirmed a specific date and time.',
  expectedResult: 'A confirmation id and the booked time.',
  handler: {
    type: 'http',
    url: 'https://api.example.com/appointments',
    method: 'POST',
  },
});
```

```yaml YAML theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
# yaml-language-server: $schema=https://roark.ai/roark-config.schema.json
kind: tool
name: book-appointment
description: Book a slot in the scheduling system
agent: frontdesk            # scope to one agent by name; omit for a project-wide tool
parameters:
  date: string
  time: string
  partySize: number
invocationCriteria: Call once the caller has confirmed a specific date and time.
expectedResult: A confirmation id and the booked time.
handler:
  type: http
  url: https://api.example.com/appointments
  method: POST
```

| Field | Default | Notes |
| :- | :- | :- |
| `name` | | The local key (`^[a-z0-9][a-z0-9-_.]*$`) and, with the kind, the config identity |
| `description` | | What the tool does, in plain language. Used to judge whether the agent reached for the right tool |
| `parameters` | | A flat map of parameter name to its type: `string`, `number`, or `boolean` |
| `invocationCriteria` | | When the tool should fire. Roark grades the call against this |
| `expectedResult` | | What a successful result looks like. Shapes the mock Roark returns to the agent |
| `agent` | project-wide | The `name` of a [`kind: agent`](https://docs.roark.ai/documentation/config-as-code/agents) to scope the tool to. Omit for a tool every agent in the project can use |
| `handler` | | How the tool executes (see [Handler](#handler)). Optional; reference metadata only |

> [!NOTE]
>
> A tool definition is **grading and mock metadata**, not an integration. In a simulation Roark scores whether your agent called the tool correctly and returns a mock result so the call can continue; it does **not** execute your backend. Defining a tool changes how Roark evaluates tool use, nothing about how your live agent runs.

## Parameters

`parameters` is a flat map of parameter name to its type, one of `string`, `number`, or `boolean`. It describes the arguments the agent is expected to pass, so Roark can check the call carried the right ones:

```typescript TypeScript theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
parameters: {
  date: 'string',
  time: 'string',
  partySize: 'number',
  waitlist: 'boolean',
}
```

```yaml YAML theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
parameters:
  date: string
  time: string
  partySize: number
  waitlist: boolean
```

## Handler

`handler` records **how** the tool executes. Today it is reference metadata, like an agent's prompt: Roark stores it but does not call it. It is read by the hosted runtime and connected-provider push once those consume it, so declaring a handler does not by itself run the tool.

It is optional. One shape exists today, an `http` handler, a public endpoint the tool's invocation would be dispatched to:

```typescript TypeScript theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
handler: {
  type: 'http',
  url: 'https://api.example.com/appointments',
  method: 'POST', // optional; GET | POST | PUT | PATCH | DELETE
}
```

```yaml YAML theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
handler:
  type: http
  url: https://api.example.com/appointments
  method: POST   # optional; GET | POST | PUT | PATCH | DELETE
```

* `type` is `http` (the discriminator that keeps future handler shapes additive).
* `url` is a public `http(s)` endpoint.
* `method` is optional, one of `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`.

> [!NOTE]
>
> For the full field reference of every kind, see the [Config DSL reference](https://roark.ai/roark-config.schema.json) schema.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.