> ## 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.

# 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 }) => {
    const company = uses.enricher({
      prompt: `Which company owns the email domain of ${input.email}?`,
    });
    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>