Tools

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.

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-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` to scope the tool to. Omit for a tool every agent in the project can use
`handler`		How the tool executes (see Handler). Optional; reference metadata only

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:

parameters: {
  date: 'string',
  time: 'string',
  partySize: 'number',
  waitlist: 'boolean',
}

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:

handler: {
  type: 'http',
  url: 'https://api.example.com/appointments',
  method: 'POST', // optional; GET | POST | PUT | PATCH | DELETE
}

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.

For the full field reference of every kind, see the Config DSL reference schema.

Getting Started

Simulations

Observability

Metrics

Config as Code

Autoimprove

Recipes

Integrations

Enterprise

SDKs & Developer Tools

Resources

Parameters

Handler

​Parameters

​Handler

Parameters

Handler