Tool Invocations

Overview

Tool invocations allow you to capture and analyze the tools used during calls. This documentation covers how to submit tool calls, parameter options, result formats, and how Roark tracks versioning for tools.

Submitting Tool Calls

Tool calls can be submitted as part of your post-call-analysis by including a toolInvocations array in your request payload when you create the call. If your tool data is not ready at call-creation time, you can also attach it afterward. Each tool invocation requires:

name: The name of the tool being invoked
description: A brief description of what the tool does
startOffsetMs: The start time offset in milliseconds with respect to the start of the call
endOffsetMs: The end time offset in milliseconds with respect to the start of the call
parameters: The parameters passed to the tool
result: The result of the tool invocation

{
  recordingUrl: 'https://example.com/recording.wav',
  callDirection: 'INBOUND',
  interfaceType: 'WEB',
  startedAt: '2025-03-29T15:30:00Z',
  isTest: false,
  properties: {},
  participants: [
    {
      name: 'Sales Agent',
      phoneNumber: '+15551234567',
      role: 'AGENT',
      spokeFirst: true,
    },
    {
      name: 'John Doe',
      phoneNumber: '+15557654321',
      role: 'CUSTOMER',
      spokeFirst: false,
    },
  ],
  // Tool invocations are passed as part of the post-call-analysis payload
  toolInvocations: [
    {
      name: 'getDentalAppointments',
      description: 'Get available dental appointments',
      startOffsetMs: 2000,
      endOffsetMs: 3000,
      parameters: {
        patientName: 'John Doe',
        patientPhone: '+1234567890',
      },
      result: { 
        appointments: ['cleaning', 'whitening', 'rootCanal'] 
      },
    },
    // More tool invocations...
  ],
}

{
  "recordingUrl": "https://example.com/recording.wav",
  "callDirection": "INBOUND",
  "interfaceType": "WEB",
  "startedAt": "2025-03-29T15:30:00Z",
  "isTest": False,
  "properties": {},
  "participants": [
    {
      "name": "Sales Agent",
      "phoneNumber": "+15551234567",
      "role": "AGENT",
      "spokeFirst": True,
    },
    {
      "name": "John Doe",
      "phoneNumber": "+15557654321",
      "role": "CUSTOMER",
      "spokeFirst": False,
    },
  ],
  # Tool invocations are passed as part of the post-call-analysis payload
  "toolInvocations": [
    {
      "name": "getDentalAppointments",
      "description": "Get available dental appointments",
      "startOffsetMs": 2000,
      "endOffsetMs": 3000,
      "parameters": {
        "patientName": "John Doe",
        "patientPhone": "+1234567890",
      },
      "result": { 
        "appointments": ["cleaning", "whitening", "rootCanal"] 
      },
    },
    # More tool invocations...
  ],
}

Attaching Tool Calls After a Call

Sometimes your tool data is not ready when the call is created, for example when a Roark simulation has finished but your backend needs a moment to assemble the tool calls, or when you submit a call before its tools are available. In those cases you can attach tool invocations to an existing call:

POST /v1/call/{callId}/tool-invocations

The body takes the same toolInvocations array as call creation:

curl -X POST https://api.roark.ai/v1/call/{callId}/tool-invocations \
  -H "Authorization: Bearer $ROARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "toolInvocations": [
      {
        "name": "getDentalAppointments",
        "description": "Get available dental appointments",
        "startOffsetMs": 2000,
        "endOffsetMs": 3000,
        "parameters": { "patientName": "John Doe" },
        "result": { "appointments": ["cleaning", "whitening"] }
      }
    ]
  }'

The response reports how many invocations were added and how many were skipped.

Attaching is idempotent. Re-sending an invocation that is already on the call (same tool name and timing) is skipped rather than duplicated, so a retried request converges instead of double-counting.

To score the tool metrics over the newly attached tools in the same request, pass a metrics array of metric definition IDs. This starts a metric collection job (billed, and requires the metric:create permission). Omit it to attach tools only. If scoring can’t be started (for example, insufficient credits), the tools are still attached and the response returns a metricCollectionError you can act on.

Tracking Input Parameters

Parameters can be submitted in two different formats:

Simple Key-Value Pairs

The most basic format is a simple key-value pair. Roark will automatically infer the type of the parameter, and rely on the name of the parameter to understand the context.

parameters: {
  patientName: 'John Doe',
  appointmentType: 'cleaning',
}

parameters = {
  "patientName": "John Doe",
  "appointmentType": "cleaning",
}

Detailed Key-Value Pairs

To ensure that the usage of the tool is clear and the types are correctly inferred, you can manually provide the description and type for each parameter. Type can be one of: string, number, boolean.

parameters: {
  patientName: {
    value: 'John Doe',
    description: 'Name of the patient', // optional
    type: 'string', // optional
  },
  appointmentType: {
    value: 'cleaning',
    description: 'Type of dental appointment',
    type: 'string',
  }
}

parameters = {
  "patientName": {
    "value": "John Doe",
    "description": "Name of the patient",  # optional
    "type": "string", # optional
  },
  "appointmentType": {
    "value": "cleaning",
    "description": "Type of dental appointment",
    "type": "string",
  }
}

Tracking Results

The result returned by the tool can be a string or a JSON object.

String Results

For simple responses, you can pass in a string:

result: 'Success'

result = "Success"

JSON Object Results

For structured data, you can pass a JSON object:

result: {
  appointments: ['cleaning', 'whitening', 'rootCanal'],
  nextAvailable: '2025-04-15T10:00:00Z'
}

result = {
  "appointments": ["cleaning", "whitening", "rootCanal"],
  "nextAvailable": "2025-04-15T10:00:00Z"
}

Tool Execution Duration

Roark calculates execution duration automatically using the difference between startOffsetMs and endOffsetMs:

startOffsetMs: Time offset (in milliseconds) from the beginning of the call when the tool execution started
endOffsetMs: Time offset (in milliseconds) from the beginning of the call when the tool execution ended

// This tool invocation lasted 1000ms (1 second)
{
  name: 'getDentalAppointments',
  startOffsetMs: 2000,  // 2 seconds into the call
  endOffsetMs: 3000, // 3 seconds into the call
  // ...
}

# This tool invocation lasted 1000ms (1 second)
{
  "name": "getDentalAppointments",
  "startOffsetMs": 2000,  # 2 seconds into the call
  "endOffsetMs": 3000, # 3 seconds into the call
  # ...
}

Tool Versioning

The system automatically tracks changes to your tool calls and creates new versions when:

A tool with the same name receives a different schema for input parameters
A tool with the same name is called with a different description

Example

If you previously called a tool:

{
  name: 'bookAppointment',
  description: 'Book a dental appointment',
  parameters: { patientName: 'string', appointmentType: 'string' }
}

{
  "name": "bookAppointment",
  "description": "Book a dental appointment",
  "parameters": { "patientName": "string", "appointmentType": "string" }
}

And later change it to:

{
  name: 'bookAppointment',
  description: 'Book a dental appointment for the client',
  parameters: {
    patientName: 'string',
    patientPhone: 'string',
    appointmentType: { type: 'object' }
  }
}

{
  "name": "bookAppointment",
  "description": "Book a dental appointment for the client",
  "parameters": {
    "patientName": "string",
    "patientPhone": "string",
    "appointmentType": { "type": "object" }
  }
}

The system will automatically create a new version to track these changes.

Getting Started

Simulations

Observability

Metrics

Config as Code

Recipes

Integrations

Enterprise

SDKs & Developer Tools

Resources

Overview

Submitting Tool Calls

Attaching Tool Calls After a Call

Tracking Input Parameters

Simple Key-Value Pairs

Detailed Key-Value Pairs

Tracking Results

String Results

JSON Object Results

Tool Execution Duration

Tool Versioning

Example

​Overview

​Submitting Tool Calls

​Attaching Tool Calls After a Call

​Tracking Input Parameters

​Simple Key-Value Pairs

​Detailed Key-Value Pairs

​Tracking Results

​String Results

​JSON Object Results

​Tool Execution Duration

​Tool Versioning

​Example

Overview

Submitting Tool Calls

Attaching Tool Calls After a Call

Tracking Input Parameters

Simple Key-Value Pairs

Detailed Key-Value Pairs

Tracking Results

String Results

JSON Object Results

Tool Execution Duration

Tool Versioning

Example