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. 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
• endTimeOffsetMs: 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,
      endTimeOffsetMs: 3000,
      parameters: {
        patientName: 'John Doe',
        patientPhone: '+1234567890',
      },
      result: { 
        appointments: ['cleaning', 'whitening', 'rootCanal'] 
      },
    },
    // More tool invocations...
  ],
}

​

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',
}

​

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',
  }
}

​

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'

​

JSON Object Results

For structured data, you can pass a JSON object:

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 endTimeOffsetMs:

• startOffsetMs: Time offset (in milliseconds) from the beginning of the call when the tool execution started
• endTimeOffsetMs: 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
  endTimeOffsetMs: 3000, // 3 seconds into the call
  // ...
}

​

Tool Versioning

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

1. A tool with the same name receives a different schema for input parameters
2. 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' }
}

And later change it to:

{
  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.