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

# Run a tool on call events

> Run a supported tool automatically at a specific point in the call lifecycle.

Use system invocation when a tool must run because an event occurred, not
because the model decided to call it. You configure invocation on the
attachment, so one tool can remain model-invoked elsewhere.

## Model invocation and system invocation

| Mode | Decision maker | Typical use |
| - | - | - |
| `model` | The large language model selects the tool from its instructions and arguments | Lookups and actions requested during the conversation |
| `system` | The call runtime matches a configured event | Logging, notifications, and deterministic follow-up work |

Use system invocation for lifecycle work that must happen consistently. The
model does not participate in the decision.

## Supported events

| Event | Runs when | Available for |
| - | - | - |
| `call_start` | The call session starts | API Request, Custom Code, Current date and time, User phone number |
| `first_user_message` | The first caller message is available | API Request, Custom Code, Current date and time, User phone number |
| `call_end` | The call ends | API Request, Current date and time, User phone number |
| `tool_succeeded` | A selected source attachment succeeds | API Request, Custom Code, Current date and time, User phone number |
| `tool_failed` | A selected source attachment fails | API Request, Custom Code, Current date and time, User phone number |

Custom Code cannot run on `call_end`. MCP, Send SMS, and call-control tools do
not support system invocation.

## Configure the attachment

<Steps>
  <Step title="Select system invocation">
    On the tool attachment, select **Run automatically** in the Dashboard or set
    `invocation` to `system` in the API.
  </Step>

  <Step title="Choose the triggers">
    Add at least one event. For `tool_succeeded` or `tool_failed`, also select
    the source attachment. The API requires its `attachment_id` as
    `source_attachment_id`.
  </Step>

  <Step title="Map the arguments">
    Map each tool argument from a constant, a template, transcript messages,
    transcript text, or call context. Mark it required only when the tool cannot
    run without that value.
  </Step>

  <Step title="Test the event">
    Save the agent and place a test call that reaches the trigger. Confirm the
    execution status and arguments in the call details.
  </Step>
</Steps>

```json System attachment theme={null}
{
  "attachment_id": "6c944f13-42dc-47e0-a11e-d55cf44ee633",
  "tool_id": "c5d52e6f-96a7-4f04-a99d-65562b9c9d52",
  "version": 2,
  "description": "Store the transcript when the call ends.",
  "invocation": "system",
  "system": {
    "triggers": [
      {
        "event": "call_end"
      }
    ],
    "arguments": [
      {
        "name": "transcript",
        "type": "transcript_text",
        "required": true,
        "description": "The complete call transcript as text.",
        "source": {
          "type": "transcript_text",
          "max_messages": 200
        }
      },
      {
        "name": "call_id",
        "type": "string",
        "required": true,
        "description": "The SLNG call identifier.",
        "source": {
          "type": "call_id"
        }
      }
    ]
  },
  "argument_overrides": {}
}
```

Add this object to `tool_refs` with the safe partial-update procedure in
[Attach a tool to an agent](/guides/agents/tools-and-mcp/attach-to-an-agent).

## Available argument sources

| Source | Value |
| - | - |
| Constant | A fixed JSON value |
| Template | Text built from inputs, runtime memory, or call context |
| Transcript messages | Structured transcript messages, optionally limited by count |
| Transcript text | Plain transcript text, optionally limited by count |
| Call context | `call_id`, `room_name`, `job_id`, `agent_id`, `agent_name`, `phone_number`, `first_user_message`, `trigger_event`, or `call_end_reason` |

`first_user_message` is unavailable at `call_start`. `call_end_reason` is only
available at `call_end`. `phone_number` is unavailable for web calls. Runtime
memory is not populated for `call_start` or `first_user_message`.

## Handle results and failures

The call record shows each system tool execution as succeeded, failed, or timed
out. Use `tool_succeeded` and `tool_failed` triggers when one tool should start
after a specific source attachment finishes. This creates an explicit chain and
avoids relying on the model to coordinate the tools.

If the source attachment fails, only a matching `tool_failed` trigger runs.
Review the execution error and mapped arguments in the call details before
retrying the workflow.


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