Skip to main content
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 }) => {
    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

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

ContextHow
On demandcargo-ai orchestration run create, or the Trigger tab
In a playreference it in a workflow via uses
From an agentlist it in the agent’s tools
Over MCPinclude it in defineMcpServer
Public formexpose the tool as an embeddable form — see Public form
APIPOST /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.