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

# Tool Invocations

> Submit and track tool calls as part of post-call analysis

### 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
* `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

<CodeGroup>
  ```typescript TypeScript {22-38} theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
  {
    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...
    ],
  }
  ```

  ```python Python {22-38} theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
  {
    "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...
    ],
  }
  ```
</CodeGroup>

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

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
  parameters: {
    patientName: 'John Doe',
    appointmentType: 'cleaning',
  }
  ```

  ```python Python theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
  parameters = {
    "patientName": "John Doe",
    "appointmentType": "cleaning",
  }
  ```
</CodeGroup>

#### 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`.

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
  parameters: {
    patientName: {
      value: 'John Doe',
      description: 'Name of the patient', // optional
      type: 'string', // optional
    },
    appointmentType: {
      value: 'cleaning',
      description: 'Type of dental appointment',
      type: 'string',
    }
  }
  ```

  ```python Python theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
  parameters = {
    "patientName": {
      "value": "John Doe",
      "description": "Name of the patient",  # optional
      "type": "string", # optional
    },
    "appointmentType": {
      "value": "cleaning",
      "description": "Type of dental appointment",
      "type": "string",
    }
  }
  ```
</CodeGroup>

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

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
  result: 'Success'
  ```

  ```python Python theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
  result = "Success"
  ```
</CodeGroup>

#### JSON Object Results

For structured data, you can pass a JSON object:

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
  result: {
    appointments: ['cleaning', 'whitening', 'rootCanal'],
    nextAvailable: '2025-04-15T10:00:00Z'
  }
  ```

  ```python Python theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
  result = {
    "appointments": ["cleaning", "whitening", "rootCanal"],
    "nextAvailable": "2025-04-15T10:00:00Z"
  }
  ```
</CodeGroup>

### 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

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
  // This tool invocation lasted 1000ms (1 second)
  {
    name: 'getDentalAppointments',
    startOffsetMs: 2000,  // 2 seconds into the call
    endOffsetMs: 3000, // 3 seconds into the call
    // ...
  }
  ```

  ```python Python theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
  # This tool invocation lasted 1000ms (1 second)
  {
    "name": "getDentalAppointments",
    "startOffsetMs": 2000,  # 2 seconds into the call
    "endOffsetMs": 3000, # 3 seconds into the call
    # ...
  }
  ```
</CodeGroup>

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

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
  {
    name: 'bookAppointment',
    description: 'Book a dental appointment',
    parameters: { patientName: 'string', appointmentType: 'string' }
  }
  ```

  ```python Python theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
  {
    "name": "bookAppointment",
    "description": "Book a dental appointment",
    "parameters": { "patientName": "string", "appointmentType": "string" }
  }
  ```
</CodeGroup>

And later change it to:

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
  {
    name: 'bookAppointment',
    description: 'Book a dental appointment for the client',
    parameters: {
      patientName: 'string',
      patientPhone: 'string',
      appointmentType: { type: 'object' }
    }
  }
  ```

  ```python Python theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
  {
    "name": "bookAppointment",
    "description": "Book a dental appointment for the client",
    "parameters": {
      "patientName": "string",
      "patientPhone": "string",
      "appointmentType": { "type": "object" }
    }
  }
  ```
</CodeGroup>

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