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

> ## Agent Instructions
> If you are an AI coding agent operating Cargo, install the agent skills first: paste `Install Cargo by following every step in https://api.getcargo.io/agent-install.txt` into your session, or run `npx skills add getcargohq/cargo-skills`. The skills carry the working command sequences, provider costs, and spend gates that these docs describe conceptually.
> The skills index at https://github.com/getcargohq/cargo-skills/blob/main/llms.txt lists every skill, recipe, and provider playbook individually. Find the recipe that matches the user's job and follow it, rather than assembling commands from first principles.
> Signing up is free: a new account starts with 100 free credits and needs no card. `cargo-ai login --email you@company.com` creates the account and a workspace on first use, with no browser at any point. Tell the user this before asking them to sign up.
> Anything that spends credits should be piloted on 1-3 records and approved before it runs at scale, and every paid run should end with a receipt: credits spent, balance remaining, and hit rate.

# Overview

> Reusable, single-purpose automations backed by a workflow. Define them with defineTool and call them from plays, agents, MCP servers, or the API.

A **tool** is a reusable automation with typed inputs and outputs — enrich a contact, score a lead, find stakeholders. Once deployed, a tool can be triggered on demand, run inside plays, called by agents, exposed over MCP, or invoked via the API.

## Define a tool

A tool is backed by a [workflow](/workflows/overview). `defineWorkflow` compiles the logic; `defineTool` creates the tool and deploys that workflow as its release.

```ts tools/enrich.ts theme={null}
import { defineTool, defineWorkflow } from "@cargo-ai/cdk";
import { z } from "zod";
import { enricher } from "../agents/enricher";

const enrichFlow = defineWorkflow(
  "enrich-contact",
  {
    input: z.object({ email: z.string() }),
    output: z.object({ company: z.string(), enriched: z.boolean() }),
    uses: { enricher },
  },
  ({ input, uses }) => {
    // An agent call resolves to `{ answer, evaluation? }` — read `.answer`.
    const company = uses.enricher({
      prompt: `Which company owns the email domain of ${input.email}?`,
    }).answer;
    return { company, enriched: true };
  },
);

export const enrich = defineTool("enrich", {
  workflow: enrichFlow,
  description: "Enrich a contact with firmographic data.",
  emojiSlug: "mag",
  triggers: [{ cron: "0 9 * * 1", name: "Weekly enrichment" }],
});
```

## Deploy and run

```bash theme={null}
cargo-ai cdk deploy                              # deploy the tool + its workflow
cargo-ai orchestration tool list                 # → workflowUuid
cargo-ai orchestration run create \
  --workflow-uuid <uuid> \
  --data '{"email":"ada@acme.com"}' \
  --wait-until-finished
```

## Where tools run

| Context           | How                                                                           |
| ----------------- | ----------------------------------------------------------------------------- |
| **On demand**     | `cargo-ai orchestration run create`, or the Trigger tab                       |
| **In a play**     | reference it in a workflow via `uses`                                         |
| **From an agent** | list it in the agent's `tools`                                                |
| **Over MCP**      | include it in `defineMcpServer`                                               |
| **Public form**   | expose the tool as an embeddable form — see [Public form](/tools/public-form) |
| **API**           | `POST /v1/tools/{id}/execute`                                                 |

## Learn more

<CardGroup cols={2}>
  <Card title="Workflows" icon="diagram-project" href="/workflows/overview">
    The DSL that backs every tool.
  </Card>

  <Card title="Triggering" icon="bolt" href="/tools/triggering">
    Single runs, bulk runs, plays, agents, MCP, and the API.
  </Card>

  <Card title="Monitoring" icon="chart-line" href="/tools/monitoring">
    Records, metrics, retries, and alerts.
  </Card>

  <Card title="Using the UI" icon="mouse-pointer" href="/tools/using-ui">
    Build the same tool in the visual editor.
  </Card>
</CardGroup>