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. defineWorkflow compiles the logic; defineTool creates the tool and deploys that workflow as its release.

tools/enrich.ts

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

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":"[e-mail]"}' \
  --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
API	POST /v1/tools/{id}/execute

Learn more

Workflows

The DSL that backs every tool.

Triggering

Single runs, bulk runs, plays, agents, MCP, and the API.

Monitoring

Records, metrics, retries, and alerts.

Using the UI

Build the same tool in the visual editor.