# Automations as tools for your agents

Let your colleagues' agents call an automation you chose. Off by default, reviewed by a person, run as the person who asked, and in the audit log with who asked.

URL: https://docs.qaldy.com/mcp/agent-tools/

Some automations are useful to a person at a prompt: "send the weekly unpaid invoices now", "check stock for this SKU". An automation can be published as a **tool**, so that the agents of the people in your workspace see it in their tool list, with a name, a description and the inputs you chose. Calling it starts the automation.

:::preview Preview
Built and tested end to end. It returns **how the run ended**, not data: its effects are in the apps it changed. Returning a result is [[Planned]].
:::

## What publishing is, and is not

- **Off by default.** No automation is a tool until a person turns it on.
- **It changes what an agent can see, not what it may do.** A call runs through the normal run path **as the person whose sign-in or token the agent uses**. That person must be able to run the automation, the app must be live, the monthly allowance and the [spending cap](https://docs.qaldy.com/guides/spending-cap/) hold, and the gate decides what the app can reach. An agent never gets more than its person has.
- **It needs a review.** You read the permissions of the app that will run, as plain sentences, and the console sends back a hash of what was shown. If the app's permissions change later (a new connector action, a new address, AI) the hash no longer matches, the tool shows as **needs review**, and agents stop seeing it until a person reads the new permissions and publishes again.
- **Only a person in the console** can publish, change, switch off or take back a tool, and only an editor of its app. A personal access token cannot: the review is a person's.

![An automation open in the console, with its Agent tool card: Publish as a tool and what agents see.](https://docs.qaldy.com/screens/agent-tool.webp "The Agent tool card on an automation. Sample data.")

## Publish one

Open the automation under **Automations**. On its **Agent tool** card press **Publish as a tool**, read what it may do, and fill in:

| Field | Rule |
|---|---|
| Name | `snake_case`, 3 to 48 characters, unique in the workspace. Cannot be the name of a built-in tool or start with `qaldy_`, `mcp_` or `system_` |
| Title | Up to 60 characters |
| Description | 8 to 400 characters. Agents read it, so say what the automation does and when to use it |
| Inputs | Up to 20 fields: text (with a length, a list of allowed values or a format such as date, date-time, email or link), number, whole number, true or false, or a short list. Each can be required |

The input schema is a small subset of JSON Schema on purpose. Anything else (`$ref`, `pattern`, nested objects, `oneOf`) is refused when you save. Every call is checked against it by the API, and unknown fields are refused, never dropped.

An app can be started by an agent when its manifest declares a `manual`, `webhook`, `form` or `schedule` trigger. The input reaches the app as `event.input`, like a webhook's body. An app that starts only from an event cannot be a tool.

## What an agent sees and gets back

The tool's description says the automation's name and app, who published it, that it is limited to what the app is allowed to do, and then your own words, **marked as yours**. The tool is marked as able to change things and reach other services, so clients that confirm writes will confirm it.

A call waits a few seconds for the run to end and answers with how it ended: finished (with how long), failed (with the error **code** and a pointer to `inspect_run`), stopped by the gate, waiting for a person to approve a step, or still running. The answer never carries the app's own error message: that was written by running code, so it stays behind `inspect_run`, where it is marked as data.

## States

| State | Meaning | Do agents see it? |
|---|---|---|
| Live | Published, switched on, permissions as reviewed | Yes, if the person can run it |
| Off | Switched off by its owner | No |
| Needs review | The app's permissions changed after the review | No |
| Paused | The automation or its app is paused | No |

## Who asked

A run started through a tool shows who asked: the person, the tool's name and the client. The audit log has two rows for it, both naming the agent: `run.start` and `mcp.tool_call` (tool name, automation, app, person, client, how many fields were passed, never the values). Publishing and taking back are `mcp.tool_publish`, `mcp.tool_update`, `mcp.tool_on`, `mcp.tool_off` and `mcp.tool_unpublish`. A run started from the console's own **Try it** button is marked as a test, not as an agent.

## Limits

30 calls a minute for one person and tool, then `429 tool_rate_limited`. At most 32 KB of input per call. A call that does not fit the schema starts nothing.

## Not built

- A **result** returned to the caller. [[Planned]]
- A confirmation on every call, and allow-lists per role.
- Tools from outside MCP servers placed behind the gate.