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