AutomationTools

Code tools

Overview
Not sure where to begin? Explore our Getting started guidelines to set up your first AI Agent, review Key concepts to understand the essentials, or check out Improvement tactics to resolve issues and keep things running smoothly.

A code tool runs a small piece of Python to clean up, transform, or compute data before your AI Agent uses it.

It’s the next step up from an API tool. An API tool calls an external endpoint and hands the whole response to the AI Agent. A code tool calls the same endpoint (or runs on its own), runs the Python on the result, and returns only what the Agent needs.

Two things make this better than passing a raw API response to the Agent:

  • Less for the AI Agent to parse: you decide exactly what it receives, instead of a full response it has to read through.
  • A consistent result: the same input always produces the same output, so calculations and formatting do not drift between conversations.
Code tools

Which tool to use

Two tool types connect an AI Agent to data and systems. Choose based on what the Agent needs to do with the result.

SituationTool
Fetch or send data, and the response is already usable as-isAPI tool
Reshape, trim, compute, or format a response before the Agent uses itCode tool
Run logic that must produce the same result every timeCode tool

How code tools work

A code tool is authored via Ada’s MCP Server (the connection an AI assistant uses to create and manage tools on your Agent) or the Platform API. There are two authoring paths, both covered in Create a code tool:

  • Describe it over Ada’s MCP Server: connect an AI assistant and describe the tool in plain language. The assistant writes the code, inputs, outputs, and environment variables, and stages the tool as a draft (a change set). It goes live only when you promote it.
  • Push code through the Platform API: for developers with code already written, a push writes the tool directly.

Once a tool is created, you can edit its code from the dashboard, over Ada’s MCP Server, or through the Platform API.

Adding a code tool to a Playbook step is the recommended way to run it mid-conversation, but it’s optional. A code tool can also run standalone, like an API tool, with the AI Agent calling it when relevant. For the parts that make up a tool, see Inputs, outputs, and environment.

What you can build

Common uses of a code tool:

  • Trim a large API response: return only the three fields the Agent needs from a response with hundreds of them.
  • Map codes to clear labels: convert a status code such as AWAIT_FUL into “Awaiting fulfillment” before the Agent uses it in a reply.
  • Run exact calculations: compute a refund total or proration the same way every time, rather than relying on the Agent to do the math.
  • Format by region: format a date, currency, or address to match the end user’s locale.

Guardrails

Every run is sandboxed, with these limits:

  • Language: Python only, a restricted subset, not full Python. A few standard-library modules can be imported; no classes.
  • Compute time: about 5 seconds per run.
  • Total time: a roughly 65-second ceiling end to end, including any network calls.
  • Result type: text, a number, true/false, a list, or an object. A code tool cannot return files or images.
  • Network access: deny-by-default. Code can only reach domains you add to the allowed-domains list, plus your own Ada instance, which is always permitted. Internal and metadata addresses are always blocked, and redirects are not followed.

For the full limits and guidance on writing effective tools, see Limits and best practices.

Have any questions? Contact your Ada team, or email us at .