# Tools

Turn on the actions the agent can take, set who approves them, test them, and manage them in bulk

Tools are the actions the Risotto agent can take while it works a request, such as creating a Slack channel, resetting an Okta password, or updating the ticket. You reference tools in [runbooks](https://www.tryrisotto.com/docs/dashboard/runbooks#using-tools-in-runbooks) and [automations](https://www.tryrisotto.com/docs/dashboard/automations), and the [Assistant](https://www.tryrisotto.com/docs/dashboard/assistant) can use them too. Find them at **Tools** in the dashboard sidebar.

## The Tools page

The **Tools** page lists every tool in a rail of groups on the left and the selected group's tools on the right. The rail has three sections:

- **Departments**: **Org-wide**, then one group for each department. A tool you set up is listed under the department it belongs to.
- **Risotto**: **Risotto Tools** (the [core tools](#core-tools) and [Risotto's own actions](#risotto-tools)) and **Script** (your [script tools](https://www.tryrisotto.com/docs/integrations/tools/script-tools)).
- **Platforms**: one group for each platform, such as Okta or Slack, for each [MCP server](https://www.tryrisotto.com/docs/integrations/tools/external-mcp-servers), and for each [custom API source](https://www.tryrisotto.com/docs/integrations/tools/custom-api-tools).

A tool you set up shows in two groups: its department and its source. Each group shows how many of its tools are enabled. Use **Search tools** to filter by name, description, department, or platform.

Each row shows the tool's name, its source, and its description. A row can also show:

| Mark                                    | Meaning                                                                                                      |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Faded row with **Enable** or **Set up** | A tool template that you haven't turned on yet.                                                              |
| Shield icon                             | The tool runs with [approval](#require-approval).                                                            |
| **Setup required**                      | The tool is missing a required setting. Open the tool and click **Edit**.                                    |
| **Not connected**                       | The tool needs a connector that isn't set up, for example the Slack Tools connector.                         |
| **Needs reauth**                        | The tool's connector is missing permissions. Reconnect it.                                                   |
| **Update**                              | A newer version of the tool's template is available. Open the tool and click **Upgrade Tool**.               |
| **Upgrading**                           | An upgrade was started and not finished. Open the tool and click **Continue Upgrade** or **Cancel Upgrade**. |
| Switch                                  | Turns the tool on or off. The agent can use only enabled tools.                                              |

Org Admins and Managers see every tool, and only they can set up, change, or delete tools. Other users see the tools of the departments they belong to, as a Supervisor or an agent, and of those departments' sub-departments. See [Permissions](https://www.tryrisotto.com/docs/operating/permissions).

## Core tools

Core tools are built into Risotto. They are always available to the agent: you don't turn them on, and a runbook doesn't need to reference them. They don't count toward the limit of 10 tools per runbook. They are listed under **Risotto Tools**; click one to read its description.

| Tool                       | What it does                                                                                                                                                                                                                                                                                                  |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Get User Context**       | Gets the requestor's profile: their email and pronouns, and the fields your identity provider (Okta, Google, or Entra) has for them, such as name, title, team, department, manager, cost center, office location, city, state, country, and start date.                                                      |
| **Handle Access**          | Handles requests for access to software or resources: granting, extending, or revoking access, account management, group membership, and license assignment. Also confirms software or license availability.                                                                                                  |
| **Research Answer**        | Researches and answers questions and troubleshoots issues. The agent uses it for every request that isn't about software access.                                                                                                                                                                              |
| **Resolve**                | Marks the issue resolved and ends the conversation.                                                                                                                                                                                                                                                           |
| **Escalate**               | Asks a human agent for help. The ticket stays in its department. The department's escalation contact or [escalation routing](https://www.tryrisotto.com/docs/dashboard/settings/departments#escalation-routing) rules decide who is tagged or assigned. A runbook cannot move a ticket to another department. |
| **Cancel Request**         | Cancels the request.                                                                                                                                                                                                                                                                                          |
| **Leave Internal Comment** | Leaves an internal comment on the ticket. The support team sees it and the requestor never does. Risotto posts it in the ticket's thread in the agent channel, marked with a lock, and syncs it to a linked ticketing system as a private note. It does not answer the requestor.                             |
| **Request Approval**       | Stops until the approvers that the runbook step tags approve, and follows the rejection steps if they deny.                                                                                                                                                                                                   |

> **Note:** If a runbook in your organization uses a
> [form](https://www.tryrisotto.com/docs/dashboard/runbooks/forms), Risotto automatically creates a
> **Collect Structured Input** tool. It presents the form to the requester and
> records the answers. You don't add it to runbooks yourself, it doesn't count
> toward the per-runbook tool limit, and it should stay enabled.

## Risotto Tools

Risotto Tools act on Risotto itself or on your identity provider through Risotto's own connection, not on a separately configured system. They are in the **Risotto Tools** group, below the core tools. Turn one on like any other tool, then reference it from a runbook.

### Update Ticket

**Update Ticket** changes fields on the current ticket while the agent follows a runbook. The tool has no configuration. Your runbook instructions tell the agent which values to set, for example "If the laptop is lost, set the priority to urgent and set **Device status** to Lost."

In one call, the agent can change one or more of these fields:

| Field         | What the agent sends                            | What Risotto does                                                                                                                                                                                         |
| ------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Priority      | `low`, `medium`, `high`, or `urgent`            | Sets the AI-suggested priority and adds an internal note, for example "Priority changed from Medium to Urgent." If a person already set the priority, Risotto keeps that value and tells the agent.       |
| Custom fields | The field label or field ID, with the new value | Sets the department's [additional ticket fields](https://www.tryrisotto.com/docs/dashboard/settings/departments#additional-ticket-fields). If one value is not valid, Risotto changes none of the fields. |
| Assignee      | An email address                                | Assigns the ticket. The person must already be a user in your organization. If no user has that email address, the ticket stays unchanged.                                                                |

If the ticket is linked to an external ticketing system (for example, Jira), Risotto sends all the changes from the call in one sync.

> **Note:** The **Assign Ticket** tool is deprecated. You cannot add a new Assign Ticket
> tool. Assign Ticket tools that you already have continue to work, with their
> **Assignee Email** and **Allowed Assignee Emails** settings. For new runbooks,
> use **Update Ticket** to assign tickets. Update Ticket has no list of allowed
> assignees: the agent can assign the ticket to any user in your organization
> that the runbook names.

### Add User to IdP Group

**Add User to IdP Group** adds a user to a group in your identity provider: Okta, Google Workspace, Microsoft Entra ID, or JumpCloud. It uses your organization's identity provider connection, so it needs no credentials of its own. The agent passes the group from a group reference in the runbook, or the group's exact name. If the user is already a member, the tool reports that and changes nothing.

| Setting                   | Default | What it does                                                                                                                                           |
| ------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Identity provider**     | `auto`  | The identity provider to write to. `auto` uses the one that is connected. If more than one is connected, pick the one your runbook's groups come from. |
| **Restrict to requestor** | On      | The tool adds only the ticket's requestor. Turn it off to let the agent add other users for the requestor.                                             |

## Turn on a tool

Org Admins and Managers turn on tools from the templates in each platform group. A platform's tools need that platform's integration or connector, for example the Okta integration or the Slack Tools connector.

1. **Open the platform's group**

   Go to **Tools** and click the platform in the rail, for example
   **Slack**. The tools you haven't turned on yet are faded.

   *Product example: The Risotto Tools page on the Slack group: configured Slack tools, faded templates with Enable, and the tool groups rail.*

2. **Enable the tool**

   Click **Enable** on the tool's row. Risotto creates the tool with the
   template's name and description, and shows "Tool "\<name>" enabled." If
   the row shows **Set up** instead, the template has required settings:
   click **Set up** and continue with the next step.

To read what a template does and which settings it takes before you turn it on, click its row. To change the name or settings first, click **Customize** in that dialog.

*Product example: The details dialog of the Manage Slack Channel Members template, with its optional settings, Customize and Enable.*

### Set up a tool with settings

**Set up** and **Customize** open the setup form. To add a second copy of a tool with other settings, for example a second Web Search tool limited to one site, click **New \<platform> tool** below the group's tools.

1. **Name the tool**

   Enter a **Name** (up to 64 characters, unique in your organization). The
   agent sees the name and uses it to decide when to run the tool, so make it
   clear and specific. The **Description** is only for dashboard users; it
   doesn't change what the tool does.

2. **Choose the approval**

   **Requires Approval** is on for a new tool. Leave it on to have someone
   approve each run, and pick an **Approval policy** if you have one. Without a
   policy, anyone in the agent channel can approve. See [Require
   approval](#require-approval).

3. **Fill in the tool configuration**

   Fill in the fields under **Tool Configuration**. They come from the
   template, for example **Allowed Domains** for Web Search.

4. **Save the tool**

   Click **Save**. The tool is enabled unless you turned off **Enabled**.

   *Product example: The Risotto setup form for a Web Search tool: name, description, Requires Approval, Enabled, and allowed domains.*

A new tool is org-wide. To give it to a department, open the tool, click **Edit**, and choose the **Department**. See [Tool departments](#tool-departments).

> **Note:** A tool that you turn on with **Enable** also requires approval. Turn off
> approval on the tool's page if the tool doesn't need it.

## Add your own tools

Next to the search box, the **Tools** page has three buttons for Org Admins and Managers:

- **Script templates**: start a [script tool](https://www.tryrisotto.com/docs/integrations/tools/script-tools) from a ready-made script.
- **New script tool**: write a [script tool](https://www.tryrisotto.com/docs/integrations/tools/script-tools) in TypeScript that chains your tools, platform context, and APIs into one action.
- **Add Custom Integration**: turn REST API endpoints into tools with the [custom API tool](https://www.tryrisotto.com/docs/integrations/tools/custom-api-tools) wizard.

To import the tools of an MCP server, see [External MCP Servers](https://www.tryrisotto.com/docs/integrations/tools/external-mcp-servers). An MCP server's tools are listed in its own group; clicking one opens the server's page.

## The tool page

Click a tool to open its page.

*Product example: The Manage Slack Channels tool page in Risotto, with its Status, Approval and User Verification settings and side panel.*

- **Tool Details**: the template and its version, then **Status** (the **Enabled** switch), **Approval**, and **User Verification**. If a newer template version exists, click **Upgrade**.
- **Approval**: shown when the tool has an approval policy, with the policy's rules.
- **Source**, **Configuration**, and **Parameters**: the custom API endpoint, the tool's settings, and the arguments the agent sends, when the tool has them. Secret settings are masked.
- **Run history** and **Version history**: for [script tools](https://www.tryrisotto.com/docs/integrations/tools/script-tools).

The side panel shows the **Template version**, the **Department**, when the tool was created and last updated, and the runbooks and app access rules that use it. Under **Actions** are **Run tool**, **Delete**, and, when an update is available, **Upgrade Tool**.

To change the name, description, department, approval, or configuration, click **Edit** (or press `e`), make your changes, and click **Save**.

### Tool departments

A tool belongs to one department, or is org-wide. Supervisors of the tool's department can add it to their runbooks and run it from its page or over MCP. Only Org Admins and Managers can use an org-wide tool.

If you move a tool out of a department while that department's active runbooks use it, Risotto asks you to confirm in the **Move this tool to \<department>?** dialog. After the move, Supervisors of the old department cannot use the tool, and cannot save changes to those runbooks while they use it. Tickets still run the tool.

## Require approval

When a tool requires approval, Risotto asks for approval each time the agent runs the tool, and runs it only after it is approved. New tools require approval.

- To turn approval on or off, use the **Approval** switch on the tool's page. It reads **Required** or **Not required**.
- To choose who approves, attach an [approval policy](https://www.tryrisotto.com/docs/dashboard/settings/approval-policies#attaching-a-policy-to-a-tool) on the tool's edit page. The tool's page then shows a **Policy** badge instead of the switch. Without a policy, anyone in the agent channel can approve.
- A runbook can use another policy for one reference to the tool. See [A different policy for one tool reference](https://www.tryrisotto.com/docs/dashboard/settings/approval-policies#a-different-policy-for-one-tool-reference).

To watch a policy on a sensitive tool, its **Tool Approval Request** in Slack, and a different policy on one tool reference in a runbook, see [Approval policies: advanced use cases](https://www.tryrisotto.com/docs/guides/approval-policies-advanced-video).

Runs from the tool's page and MCP runs skip the approval step. When an [app access rule](https://www.tryrisotto.com/docs/dashboard/applications/access-rules) runs the tool, the access rule's own approval applies instead, and the tool's page shows **Approval not enforced for access rules**.

You cannot turn off approval for a script tool while its published version uses tools that require approval. The error message names those tools.

## User verification

Each tool's page has a **User Verification** switch. When the switch shows **Required**, the requestor must confirm who they are in Okta before the agent runs the tool. The switch works when Okta is connected or [sign-in verification](https://www.tryrisotto.com/docs/dashboard/settings/identity/sign-in-verification) is set up; otherwise the page shows **Connect Okta**.

1. The agent calls the tool. Risotto sends an Okta Verify push to the requestor's phone.
2. The status line of the ticket's Slack thread changes to "Requesting identity verification for *tool name*...". Risotto posts the details in the department's agent channel.
3. When the requestor approves the push, the agent runs the tool and continues.
4. If the requestor denies the push, or does not answer within 5 minutes, the agent does not run the tool. Risotto escalates the ticket to a human.

The requestor must have Okta Verify push enrolled in Okta. If not, Risotto escalates the ticket. User verification is separate from approval: a tool can require both.

To have requestors sign in to your own Okta or Microsoft Entra ID app instead of approving a push, use [sign-in verification](https://www.tryrisotto.com/docs/dashboard/settings/identity/sign-in-verification). The sign-in then uses the factors your app's access policy requires, such as passkeys or security keys.

## Run a tool

Org Admins, Managers, and Supervisors of the tool's department can run a tool from its page, for example to test it. This is a real run: it uses the tool's stored credentials and changes the target system, and it skips the approval step.

1. **Open the run dialog**

   On the tool's page, click **Run tool** in the side panel. The button is
   off while the tool is disabled.

2. **Run the tool**

   Fill in the tool's parameters and click **Run tool**.

   *Product example: The run dialog for Manage Slack Channels, with parameters filled in to create a channel.*

3. **Read the result**

   The dialog shows **✓ Success** with the tool's output, or **✗ Error** with
   the reason. Click **Run again** to try other values.

Risotto logs every run. You are the requestor of the run: with **Restrict to Requestor Only** on, the tool acts only on your own account or devices.

On a tool's page, press `⌘K` (`Ctrl+K` on Windows and Linux) to see the commands for that tool: **Edit tool**, **Run tool…**, **Disable tool** or **Enable tool**, and **Delete tool…**. **Run tool…** opens the same run dialog and shows only when the tool is enabled. Only Org Admins and Managers see **Enable tool**, **Disable tool**, and **Delete tool…**. Risotto refuses to delete a tool that a runbook or a script tool uses.

## Using tools in runbooks

To insert a tool into runbook instructions, type `#` or choose **Tool** from the `/` menu, then pick the tool. The tool shows as a chip with its name. The agent gets only the tools that the runbook references, plus the core tools. A runbook can use up to 10 tools. See [Using tools in runbooks](https://www.tryrisotto.com/docs/dashboard/runbooks#using-tools-in-runbooks).

## Delete a tool

On the tool's page, click **Delete**, then click **Delete Tool** in the **Delete '\<name>'?** dialog. You cannot undo a delete.

If an active runbook or a published script tool uses the tool, Risotto doesn't delete it. The **Cannot Delete Tool** dialog lists them. Click **Take me there** to open the runbook or script, remove the tool from it, and delete the tool again.

### Enable, disable, or delete many tools

Org Admins and Managers can change many tools in one action, on the **Tools** page or on the **Tools** tab of an integration.

1. **Open a group**

   Open a group of tools, for example the tools of one custom API source or
   one MCP server.

2. **Select the tools**

   Select the checkbox of each tool. Hold `Shift` and click to select a range,
   or click **Select all** to select every tool that the group shows.

3. **Choose the action**

   Click **Enable**, **Disable**, or **Delete**. **Delete** asks you to
   confirm in the **Delete N tools?** dialog. You cannot undo a delete.

   *Product example: Three tools of a custom API source selected on the Risotto Tools page, with Enable, Disable and Delete.*

You can select only tools that you set up. Templates and built-in tools do not have a checkbox. The selection holds only the tools that the group shows, so a search that hides a tool also leaves it out. The selection clears when you open another group.

Risotto changes each tool on its own and skips a tool that it cannot change. A message names each skipped tool and the reason, and the skipped tools stay selected. Risotto skips:

- A delete of a tool that an enabled runbook uses. Remove the tool from the runbook first.
- A delete of a tool that a published script tool uses. Publish a script version that does not use the tool first.
- An enable of a script tool that is not published, or that uses a tool that is turned off.

When you disable a tool, Risotto also turns off the script tools that use it. An automation that uses a deleted or disabled tool keeps running without it. Deleting an MCP tool also removes it from its server's imported tools.

## Best practices

- **Name tools for the agent.** The agent reads the name to decide when to run a tool. "Reset Okta password for requester" works better than "Okta tool 2".
- **Keep approval on for tools that change things.** Turn it off only for read-only tools, such as lookups and searches.
- **Give tools to departments.** A tool in a department lets that department's Supervisors build runbooks with it, without access to every org-wide tool.
- **Test before you reference.** Click **Run tool** with real values before a runbook depends on the tool.

Source: https://www.tryrisotto.com/docs/dashboard/tools
