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

# Run app actions during conversations

> Turn one action in a connected app, such as adding a spreadsheet row, into a tool your assistant uses on calls, in chats and by email

An app action tool lets an assistant run one action in a connected app while the conversation is still going. Examples are adding a row to a Google Sheets spreadsheet or creating a contact in HubSpot. You choose the app, the connection and the action, and Famulor turns the action's fields into a tool with real parameters. You don't need your own API endpoint or an automation.

> [!NOTE]
>
> App action tools are in Beta. Owners and admins see them once **Beta Features** is on under [Settings → Workspace](https://docs.famulor.io/settings/workspaces.md), and the workspace plan must include Automations. Other members see assigned app action tools but can't change them.

## How an app action tool works

A hair salon wants callback requests from callers in a spreadsheet. It creates an app action tool for the Google Sheets action “Add row”. The spreadsheet and the sheet are fixed values, the assistant fills in the caller's name and request, and the phone number comes from the caller ID. Before the assistant writes the row, it reads the details back and asks the caller to confirm them.

The tool appears in **Agent Tools** next to your other tools, and you assign it to assistants like any other tool. It works in every conversation channel:

* phone calls, web calls and WhatsApp calls
* web chat, including Test Chat
* every [messaging channel](https://docs.famulor.io/channels/messaging.md), such as WhatsApp, SMS, Telegram or Slack
* [email](https://docs.famulor.io/channels/email.md), both the assistant's own address and connected mailboxes

## Choose the right kind of tool

An app action tool covers exactly one action in one app. For anything else, another tool type fits better:

| You need | Use |
| - | - |
| One action in a connected app | An app action tool (this page) |
| A request to your own HTTP endpoint | An [API tool](https://docs.famulor.io/api/tools-and-webhooks.md#api-tools) |
| Several steps, conditions or apps in one run | An automation [called from the conversation](https://docs.famulor.io/automations/overview.md#calling-an-automation-from-a-conversation) |

For a single action, an app action tool is faster than a callable automation. The assistant sends each field directly, so no extra AI step has to pull the values out of a free-text request.

## Before you start

Check these requirements first:

* You're an owner or admin of the workspace.
* **Beta Features** is on under **Settings → Workspace**.
* The workspace plan includes Automations, and its **Tools & MCP** limit has room for another tool.
* The app is connected under **Automations → Connections**. You can also connect it while you create the tool.

## Create an app action tool

**1. Choose the app and the action**

Open **Agent Tools** and select **New tool → App (Beta)**. You can also start from the **Apps** card under **Agent Connectors**, where an app logo opens that app directly, or select **Use in assistant** next to an app under **Automations → Connections**. The editor lists your connected apps. To add another app, select **Connect an app**: the same app list as in Automations opens, and you return here after signing in. Then pick the action. If the app has more than one connection, choose one under **Connection**.

**2. Name the tool and say when to use it**

**Name** is prefilled, for example `google_sheets_add_row`. In **Use when**, describe the situation in which the assistant should call the tool, for example “When the caller asks for a callback.” Use at least 10 characters. A specific sentence works better than a short label.

**3. Choose where each value comes from**

Each field of the action has a **Value from** setting, described in the next section. Required fields come first. Optional fields start as **Off** under **More fields**.

**4. Decide whether the assistant asks first**

For actions that change data, **Ask first** is on. Leave it on unless the change needs no confirmation. The section on Ask first below explains how it works.

**5. Check the preview and test**

**What the assistant sees** shows the tool exactly as the assistant receives it. Run a test under **Test** before you save, as described below.

**6. Save and assign**

Select **Create tool**, then [assign the tool](https://docs.famulor.io/assistants/agent-tools.md#installed) to assistants. In an assistant's settings, **Advanced → Tools → Add tool** lists your **Connected apps**: select one to open the same editor, or select **Connect an app** to connect another app first. The tool is assigned when you select **Add to assistant**. An app action tool can't be a **Tool** step in a [flow](https://docs.famulor.io/flow-builder/nodes.md#tool) yet; assign it to the assistant instead.

## Set where each value comes from

**Value from** decides who provides the value of a field:

| Value from | The value comes from | Use it for |
| - | - | - |
| **AI** | The assistant, from the conversation | Details the customer tells you, such as a name, a request or a preferred date |
| **Fixed value** | Your entry, sent on every run | IDs of a spreadsheet, calendar, list or pipeline, and fixed labels |
| **Variable** | A conversation variable, such as **Caller number** | The caller's phone number, the customer's email address or an assistant variable |
| **Off** | Nothing: the field isn't sent | Optional fields you don't need |

For **AI** fields, Famulor writes a description from the app's field information, including the expected format, such as `YYYY-MM-DD`, and an example. Type your own description to replace it. Up to 12 fields can use **AI**. Keep it to 8 or fewer: fewer fields make calls faster and more reliable.

The assistant never sees **Fixed value** and **Variable** fields and can't change them. A fixed text can contain [variables](https://docs.famulor.io/assistants/variables.md) such as `{{caller_number}}` and the values of AI fields, written with the parameter name shown in **What the assistant sees**, for example `{{start_time}}`. When you paste a link to a Google Sheets, Docs, Drive, Notion or Airtable item, Famulor keeps only its ID.

A few more rules apply to fields:

* Phone fields start with the variable **Caller number**. On messaging channels, it holds the contact's phone number.
* Required fields can't be **Off**.
* Some fields take table rows, for example the values of a new spreadsheet row or the attendees of an event. They show **Columns**. For a spreadsheet row, select **Add column** for each value and name the column. For a list such as attendees, the app sets the columns, for example Email and Name; select **Add row** for each entry. Choose **AI**, **Fixed value** or **Variable** for each cell. A required column needs a value in every row.
* In a list such as attendees, optional columns start **Off**. Turn them on for a row when you need them. Number and yes/no cells take **AI** or **Fixed value**.

**What the assistant sees** lists the tool name, its description and every AI field. Fixed values and variables appear as not visible to the assistant. The description can be up to 900 characters long. Select the pen icon to write the description yourself. The sentences about confirming changes and about unknown outcomes always stay at the end.

## Ask first

Actions that change data, such as adding a row or creating a contact, have **Ask first** turned on by default. Actions that only read data never ask. With **Ask first** on, a change runs like this:

1. The assistant calls the tool. Nothing changes yet: Famulor returns a summary of the values.
2. The assistant reads the summary to the customer and asks whether it's correct.
3. The assistant calls the tool again with the same values. This call runs the action in the app if the condition of the channel is met:
   * In messaging and email, the customer has sent a new message since the summary.
   * On calls and in web chat, at least 4 seconds have passed since the first call. There, Famulor can't tell whether the customer answered.

A call that comes too early changes nothing, and the assistant is told to wait for the customer's answer. If a value changes in between, the assistant reads the new details back and asks again. A prepared change expires after 10 minutes on calls and in web chat, after 72 hours in email, including connected mailboxes, and after 24 hours in other messaging channels.

> [!WARNING]
>
> On calls and in web chat, **Ask first** only enforces a pause: a change can run after 4 seconds even if the customer didn't answer. In messaging and email, a change runs only after a new message from the customer. In no channel is **Ask first** a consent record: Famulor doesn't check what the customer answered and keeps no separate proof of agreement. Where you need documented consent, for example for a contract or a payment, collect it through a process built for that purpose.

You can turn **Ask first** off for a change that needs no confirmation. The assistant then changes data in the app without reading it back first.

## Test before you use it

Test every tool before you assign it to an assistant that talks to customers. Under **Test**, enter sample values for the AI and variable fields and select **Run test**:

* Actions that read data run for real.
* Actions that change data first run as a dry run, which changes nothing and shows what the assistant would read back. Select **Run for real** and confirm to make the change in the app.

The result shows whether the run succeeded, how long it took and exactly what the assistant receives. On calls, the caller waits while the action runs, so check the duration. Afterwards, try the tool in a Test Call or Test Chat with the assistant it's assigned to.

## What the assistant receives

Famulor shortens every result before the assistant reads it. It removes internal IDs, version numbers and values that look like secrets. It also cuts texts to 500 characters and lists to 10 items, and it limits the whole result to 2,000 characters.

Under **Advanced → Result**, choose **Selected fields** to keep only the fields you pick from a successful test result. Through the API, `result_config.max_chars` raises the limit to 3,500 characters. The assistant receives results marked as external data, not as instructions.

## Limits

| Limit | Value |
| - | - |
| Time per run | 12 seconds; the app must answer within 8 seconds |
| AI fields per tool | 12 |
| Tool description | 900 characters |
| Text per value | 4,000 characters |
| Result for the assistant | 2,000 characters, up to 3,500 through the API |
| Runs per tool | 60 per minute |
| Runs per workspace | 300 per minute |
| Runs per tool in one conversation | 15 per minute, including up to 5 changes (reading the details back isn't a change) |
| Actions that delete data | Not available yet |

When the app doesn't answer in time, the result depends on the action. An action that reads data didn't run, and the assistant can try again. For a change, the outcome is unknown: the assistant doesn't retry and tells the customer that the team will check.

## Edit, reconnect or delete a tool

Open the tool in **Agent Tools** to change its fields, **Use when** or **Ask first**. **Runs** lists the tool's recent runs from every channel, including messaging, email and tests. A prepared change that waits for the customer and a dry run don't appear there, because nothing ran in the app. Failed runs and runs with an unknown outcome show as errors. To use a different action, create a new tool.

* You can switch the tool to another connection of the same app.
* When a connection expires, the tool shows **Reconnect** and doesn't run until you reconnect it. Select **Reconnect** and sign in again: Famulor renews the same connection and brings you back to the tool. If the tool has unsaved changes, Famulor first asks whether to discard them. If the sign-in fails, the tool shows the error and **Reconnect** again.
* You can't delete a connection that app action tools use. Move the tools to another connection or delete them first.
* To delete an app action tool, first remove it from every assistant that uses it. Then delete it like any other tool.
* App action tools can't be moved to another workspace. Create the tool again in the other workspace.

## API, MCP, CLI and SDK

You can create, read, change and test app action tools without the dashboard. Every request needs an owner or admin credential. Listing and reading actions, and creating, changing or testing a tool, also need a workspace plan with Automations. Listing actions and reading an action need the scope `automations:read`, reading a tool needs `assistants:read`, and creating, changing or testing a tool needs both `assistants:write` and `automations:write`. As in the dashboard, creating a tool also needs **Beta Features**.

| API | MCP | CLI | SDK |
| - | - | - | - |
| `GET /api/v1/automations/connections/{id}/actions` | `list_app_actions` | `famulor list-app-actions <id>` | `client.api.listAppActions({ path: { id } })` |
| `GET /api/v1/automations/connections/{id}/actions/{action}` | `get_app_action` | `famulor get-app-action <id> <action>` | `client.api.getAppAction({ path: { id, action } })` |
| `POST /api/v1/tools/app-actions` | `create_app_action_tool` | `famulor create-app-action-tool --input tool.json` | `client.api.createAppActionTool({ body })` |
| `GET /api/v1/tools/app-actions/{toolId}` | `get_app_action_tool` | `famulor get-app-action-tool <toolId>` | `client.api.getAppActionTool({ path: { toolId } })` |
| `PATCH /api/v1/tools/app-actions/{toolId}` | `update_app_action_tool` | `famulor update-app-action-tool <toolId> --input patch.json` | `client.api.updateAppActionTool({ path: { toolId }, body })` |
| `POST /api/v1/tools/app-actions/{toolId}/test` | `test_app_action_tool` | `famulor test-app-action-tool <toolId> --input test.json` | `client.api.testAppActionTool({ path: { toolId }, body })` |

App action tools also appear in `GET /api/v1/tools` with an `app_action` summary. Assign them with `PUT /api/v1/assistants/{id}/tools`, or pass `assistant_id` when you create the tool; an unknown assistant returns `404` before the tool is created. `GET /api/v1/tools/{id}/runs` and the MCP tool `list_tool_runs` return the runs shown under **Runs**. Remove a tool from its assistants, then delete it with `DELETE /api/v1/tools/{id}`. The general `PATCH /api/v1/tools/{id}` can still rename a tool or turn it on and off; any other change there returns `409`. The general test, `POST /api/v1/tools/test` or `test_tool`, also returns `409` for an app action tool.

### Create a tool with the API

First, list the actions of a connection. `q` searches by name. Actions that delete data aren't listed.

```bash theme={null}
curl "https://app.famulor.io/api/v1/automations/connections/CONNECTION_ID/actions?q=row" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Read the details of the action you picked with `get-app-action`. They list the action's `fields`, each with its `key`, `path`, `param` and a suggested `mode`. In the create request, send only the fields you want to change, identified by `path` or `key`. You can set `mode`, `value`, `variable` and `description`; all other fields keep their suggested setting. This request creates the tool and assigns it to an assistant:

```json theme={null}
{
  "connection_id": "CONNECTION_ID",
  "action": "ACTION_ID",
  "use_when": "When the caller asks for a callback.",
  "confirmation": "ask_first",
  "assistant_id": "ASSISTANT_ID",
  "fields": [
    { "key": "spreadsheet_id", "mode": "fixed", "value": "SPREADSHEET_ID" },
    { "key": "phone", "mode": "variable", "variable": "caller_number" }
  ]
}
```

Field keys depend on the action. `confirmation` is `ask_first` or `none`; actions that read data never ask. To make sure the action hasn't changed since you read it, also send its `version`: the request then fails if the action has a newer version. Save the body as `tool.json` and send it with `famulor create-app-action-tool --input tool.json` or `POST /api/v1/tools/app-actions`.

Then test the tool. `values` holds sample values for the AI and variable fields. Use each field's `param`, the parameter name the assistant sees, not its `key`. The two often differ: the field `startTime` has the param `start_time`, and a column takes the name of the column, such as `name`. For a variable field, the variable name, such as `caller_number`, works too:

```json theme={null}
{
  "values": { "name": "Anna Weber", "request": "Call back about a color appointment" },
  "mode": "dry_run"
}
```

`mode` is `dry_run`, the default, or `live`. For an action that changes data, a live test also needs `"confirm_write": true` and changes real data in the app. The response contains `model_text`, the exact text the assistant would receive. For an action that changes data, `read_back` lists what the assistant would read back, also in a dry run.

## Next steps

> [card] [Agent Tools](https://docs.famulor.io/assistants/agent-tools.md)
>
> Assign, edit and monitor all of your workspace's tools

> [card] [App Catalog](https://docs.famulor.io/automations/app-catalog.md)
>
> Connect apps and see what they can do in automations


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