Docs

Integrations / Build your own

Script Tools

Author multi-step TypeScript tools that chain your existing tools, platform context, and APIs into one deterministic action

Script tools are custom tools whose behavior you author as TypeScript — usually by describing the workflow to the Risotto assistant, which writes the code for you. A script chains your existing Risotto tools, platform context, and raw HTTP calls into a single multi-step action that runs the same way every time: resolve a user, look up their devices, fetch a recovery key, DM it to the requestor — one tool, one approval, one auditable run.

Once published, a script tool is an ordinary Risotto tool. Agents call it when handling requests, you can reference it in runbooks alongside native tools, and the same approval, verification, logging, and audit controls apply.

To watch a script tool built in Script Studio, with its key in the credential vault, then run from a runbook after an approval, see Build your own tools, a video.

When to use a script tool

  • Runbooks are natural-language instructions the agent interprets. Best when steps need judgment or conversation — but the agent decides each next step, so execution can vary.
  • Custom API tools turn one REST endpoint into one tool. Best for single API calls.
  • Script tools run multi-step logic as code — exact order, branching, and error handling, with one call's output feeding the next. Best for workflows that must be repeatable end to end, like device remediation, chained API sequences, or grant flows.

Create a script tool

  1. Open the studio

    In the Risotto dashboard, select Tools in the sidebar and click New script tool. Give the tool a Name (for example, Reset BitLocker Key) and an optional Description: these are what agents use to decide when to call it. Click Create and open studio.

    The tool is created as a disabled draft: you can edit and test it freely, but agents can't call it until you publish and enable it.

  2. Describe the workflow

    The studio shows an assistant chat on the left and a flow chart of the code's steps beside it. Describe what the tool should do in plain language — the assistant writes the code, asks about decisions ("if the user has multiple Windows devices, pick the most recent or fail with the list?"), and revises conversationally. The flow chart updates after every change.

    The studio chat starts in Read only approval mode, so the assistant asks before it creates, changes, or publishes the script. To change this, use the Approval mode control beside the attach button, or click Approve and Enable Auto Mode on a card. The modes are the same as in the Assistant, and your organization's highest mode applies.

    Prefer to write the code yourself? Click Code in the header to open the editor. It autocompletes your organization's callable tools (tools.*), the platform library (risotto.*), HTTP verbs, and your configured secrets, and flags problems inline. Click Save draft to save — code that doesn't parse won't save, so the chart never goes stale.

  3. Test the draft

    Click Test in the studio header. Fill in the tool's parameters, then review the summary of what the run will do — any step that writes (sends a message, creates a ticket, calls a write API) is badged up front.

    During a test, "the requestor" resolves to you: a step that DMs the requestor DMs you, never an employee. As the run executes, each node in the flow chart lights up with its status and timing. A failing step expands with its error, and the assistant can read the trace and propose the fix.

  4. Publish

    Click Publish (or ask the assistant to publish — it pauses for your approval, and approving is the confirmation). Publishing atomically makes the saved draft the live version that agents and runbooks run, and records it in version history.

    If the code calls a tool that requires approval or writes, or writes ticket data, Risotto turns Requires Approval on for the tool. You cannot turn it off while the code makes those calls. http.* writes do not count (see Approvals and security).

  5. Use it

    Enable the tool, and it appears everywhere your other tools do: in the runbook editor, in the agent's tool catalog, in the dashboard assistant, and on the MCP server. See Runbooks for referencing tools in your workflows.

How the code works

A script is a single TypeScript module with no imports. Its shape:

  • input — a zod object schema that defines the tool's parameters. This becomes the tool's signature everywhere it appears.
  • A default exported function — the tool's logic. Its return value (a string) goes back to the agent.
  • Step comments — a // **Step name** comment (optionally followed by a // description line) declares a step. Steps drive the flow chart and the per-step run trace. Capability calls outside any declared step still appear as auto-named steps, so traces never under-report what ran.
  • fail("message") — ends the run with a message delivered to the agent verbatim. Use it for designed outcomes the agent should act on ("No Windows device enrolled in Intune for this user."). Uncaught errors reach the agent only as a generic failure — the full detail lands in the run trace, and the tool-error notification fires.
  • console.log(...) — captured into the run trace for debugging, never shown to the agent.

For example, a BitLocker recovery-key tool:

export const input = z.object({
  user_email: z
    .string()
    .email()
    .describe("Email of the employee who needs the recovery key")
});

export default async function run({ user_email }: z.infer<typeof input>) {
  // **Find the user in Entra**
  const user = await tools.graph.get_user({ user_id: user_email });
  if (user.status_code === 404) {
    fail(`No Entra user found for ${user_email}.`);
  }

  // **List their managed Windows devices**
  const devices = await tools.graph.list_user_managed_devices({
    user_id: user.body.id
  });
  const windows = devices.body.value.filter(
    (d) => d.operatingSystem === "Windows"
  );
  if (windows.length === 0) {
    fail("No Windows device enrolled in Intune for this user.");
  }

  // **Get the BitLocker recovery key**
  const laptop = windows.sort((a, b) =>
    b.lastSyncDateTime.localeCompare(a.lastSyncDateTime)
  )[0];
  const keys = await tools.graph.list_bitlocker_keys({
    device_id: laptop.azureADDeviceId
  });
  const key = await tools.graph.get_bitlocker_key({
    key_id: keys.body.value[0].id
  });

  // **DM the key to the requestor**
  const requestor = await risotto.requestor_context();
  await tools.slack.send_dm({
    user_ref: requestor.email,
    message: `Your BitLocker recovery key for ${laptop.deviceName}: ${key.body.key}`
  });

  return `Recovery key for ${laptop.deviceName} sent to ${requestor.email}. Ticket can be resolved.`;
}

What a script can reach

Everything a script touches outside its own logic goes through one of three capability layers. Saving the draft resolves every reference in the code against your organization's real tools; at runtime, only what the saved code calls is available — no code path can widen the tool's reach beyond what you can read in it.

Your existing tools: tools.*

Every configured, enabled tool in your organization — built-in integrations, custom API tools, and imported external MCP tools — is callable as a function, like tools.graph.get_user(...) or tools.slack.send_dm(...).

  • Calls return full results: custom API tools, MCP tools, and HTTP return structured data your code can dereference (user.body.id); built-in tools return their text results.
  • Built-in tool results are the text the agent would see, parsed as JSON when it is valid JSON. Some integrations wrap the upstream response as { status_code, body } with body still a JSON string; call JSON.parse(result.body) before reading fields. When a call returns nothing you expected, console.log the raw result on a studio test run and read its shape in the trace before changing the logic.
  • A custom API tool returns { status_code, body }. If the tool was imported from an OpenAPI or Swagger spec that describes a JSON success response, body has that type, so the type check flags a field name that the response does not have. Tools imported before September 25, 2026 and tools imported from Postman keep body typed as any.
  • Write each tool call in full where you make it, for example tools.linear.get_issue(...). The code check shows an error for code that puts tools, a namespace, or a tool into a variable or passes it as a value (for example, const linear = tools.linear). A published script with this pattern keeps running, and you see the error when you next save or publish it.
  • Credentials stay attached to the underlying tool and its connector — your code invokes capabilities and never handles the secrets behind them. This is why a script that only composes existing tools has no authentication code of its own: the connector authenticates each call.
  • Script tools can't call other script tools; they compose your integrations, not each other.

Platform context: risotto.*

A small standard library for Risotto platform context:

FunctionWhat it does
risotto.requestor_context()The person the run is for — the ticket's requester on ticket runs, you in studio tests. Returns their email and name.
risotto.find_users({ query })Search your synced user directory.
risotto.get_user_profile({ email })A user's identity provider profile.
risotto.get_manager({ email, field? })The user's manager's email, read from their identity profile.
risotto.get_ticket({ ticket_id? })Read a ticket, including its priority (value and is_suggested). Defaults to the ticket the run is for, so a script can inspect its own ticket without an input.
risotto.get_ticket_comments({ ticket_id?, include_internal? })A ticket's comments (the run's own ticket by default). Public comments only unless include_internal is true.
risotto.create_ticket({ title, description, department? })Create a Risotto ticket.
risotto.add_ticket_comment({ comment, ticket_id?, internal? })Comment on a ticket (the run's own ticket by default). Comments are internal unless you explicitly say otherwise.

The library reads platform context and writes only your organization's own tickets. Anything that acts on an external system goes through a tool or the HTTP layer below.

When an automation runs the script

A script tool can run as a tool in an automation. An automation run has no requestor, so some functions act differently:

  • risotto.requestor_context() fails with "this run has no requestor". Take the target user as a tool input instead.
  • risotto.create_ticket() fails because the run has no requestor. Use the automation's built-in Create Ticket tool to open a ticket.
  • risotto.get_ticket() and risotto.get_ticket_comments() can read any ticket in your organization. Pass ticket_id, because the run has no ticket of its own.
  • risotto.get_ticket_comments() refuses include_internal: true. Internal notes stay private to human agents.

The script's run history shows the automation run that called it.

Allowlisted HTTP: http.*

A script can call APIs directly — with or without composing any tools. Declare the domains it may reach in the code, each bound read-only or read-write:

export const domains = {
  "api.github.com": "read",
  "hooks.acme.com": "read_write"
};

Then use http.get, http.post, http.put, http.patch, or http.delete. Requests are HTTPS-only, and the domain and read/write posture are enforced on every request — a write verb against a read-only domain is refused. Widening the tool's reach (a new domain, a domain going read-write) is a code change, so it's versioned and visible in history like any other edit.

Connection auth: http.* without a secret

For Google Workspace, Microsoft Intune, and Jamf Pro, a script can use the connection that your admin already set up. Send auth: { type: "google" }, auth: { type: "intune" }, or auth: { type: "jamf" } in the http.* call. You enter no key, and the token never reaches the script.

  • Each type reaches only its own hosts: googleapis.com for Google, graph.microsoft.com for Intune, and the Jamf Pro server that your organization saved for Jamf Pro. A script that sends Jamf auth to a literal URL on another host does not save. A computed URL to another host is refused when the script runs.
  • The Assistant writes this auth for you when you ask it for a tool for one of these products.
  • If the product is not connected, the editor shows a warning such as "Jamf Pro is not connected, so a run of this tool fails. An admin connects it on Settings > Integrations > Jamf." The warning does not block the save.
  • A script that sends Intune or Jamf Pro auth never counts as read-only, even when it only reads. Its runs follow the approval mode of the Assistant or automation that runs it.
  • A Jamf Pro call has the privileges of the API role of the Risotto API client. Add to that role the privileges that each call needs.
  • Google auth declares the scopes it needs. See Google Workspace tools.

Secrets: env.*

API keys and other credentials never live in the code. Reference them as env.MY_API_KEY, and Risotto derives the tool's configuration fields from the names your code uses. Enter the values on the tool's configuration card — they're encrypted, write-only, substituted into requests only as they leave Risotto, and never appear in code, chat, or run traces. Rotate a value anytime without republishing.

Each env.* field on the configuration card is a credential vault slot. There is no vault picker in the code editor: write env.WS1_API_KEY in the code, save, then open Tools, select the script tool, and click Edit. The Tool Configuration card lists WS1_API_KEY as a required field. Click Choose a vault credential to fill it from the vault, or Add a vault credential to store a new secret inline. Use the value directly in the http.* call, for example auth: { type: "bearer", token: env.WS1_API_KEY }, and make sure the API host is listed in export const domains.

Approvals and security

A script tool is gated like every other tool — with one extra rule:

  • Requires Approval and User Verification apply before the code runs, with the same approval flow, ticket parking, and audit trail as any tool. One approval covers the whole run: tools called inside the script don't prompt again.
  • To keep that from bypassing anything, gates are floored by what the code reaches. Risotto enforces approval on the script tool, and you cannot turn it off, while the published code calls any of these:
    • A tool that requires approval, writes, or is destructive.
    • risotto.create_ticket or risotto.add_ticket_comment.
  • A custom API tool counts as read-only only when its endpoint uses GET. An endpoint with any other method (POST, PUT, PATCH, DELETE) counts as destructive. Every tool from an external MCP server also counts as destructive. A script that calls one of these tools keeps approval on, even when approval is off on that tool.
  • http.* writes to a read_write domain do not hold approval on. The domain allowlist controls those writes. A script with a read_write domain still does not count as read-only, so its runs follow the approval mode of the Assistant or automation that runs it.
  • If you turn Requires Approval off and the published code still reaches a blocking capability, Risotto refuses. The message names each blocker and the reason, for example that tools.github.orgs_create_invitation is destructive. If every blocker is only the approval switch on another tool, the message offers to turn approval off on those tools first. Any other blocker can only be removed from the code.
  • Scripts execute in an isolated, zero-permission sandbox, separate from Risotto's infrastructure and other tenants, with bounded runtime. The sandbox has no network or filesystem access of its own — every tool call, platform lookup, and HTTP request is brokered outside it, and only the capabilities the saved code declares exist inside a run.
  • Every execution — from a ticket, the assistant, MCP, or a studio test — is recorded in the audit trail with a per-step trace.

Run history and version history

The tool's detail page keeps all three:

  • Run history: every run opens into the traced flow chart — per-step status and timing, the failing step expanded with its error and captured logs. "Step 4 started failing yesterday with a 403" is diagnosable in minutes, and you can carry a failing run into the studio conversation for the fix. Detailed traces are retained for 90 days; the audit record of each tool call is permanent.
  • What it can call: what the published version can reach when it runs, in rows Calls tools, Calls Risotto, Reaches over HTTP, Uses credentials, and Uses the org's own connections. A tool that is turned off has a Disabled badge. The card shows only after you publish the first version.
  • Version history: who published each version and when. Restore republishes a previous version — approval requirements are recomputed, and the restore is itself a new version.

Editing a published tool

Open the studio from the tool's detail page (Open studio). Edits go to a draft — the published version keeps serving agents and runbooks while you iterate, so breaking the draft mid-refactor has no production consequence. Publishing swaps the draft in atomically; agents never run a half-edited tool.

One person edits at a time: if someone else has the studio open, you'll see "<name> is editing — view only" with a Take over action that notifies them.

When a tool your script uses changes

Script tools stay consistent as the tools underneath them change:

  • Deleting a tool a published script calls is blocked — the error lists the script tools that depend on it.
  • Disabling such a tool disables the dependent script tools too, with a notification — a clean "tool unavailable" instead of a script failing mid-run.
  • Upgrades that change a tool's parameters automatically re-check dependent scripts. Compatible scripts keep running untouched; provably broken ones are disabled with a notification, and the assistant proposes the one-line fix in the studio.

Something wrong or missing? Report an issue · View as Markdown