Tools & actions

Give an agent callable operations — your tools, connector actions, sub-agents, and MCP servers — on defineAgent.

Actions transform your agent from a reasoning engine into an action-taker. In code, you give an agent its callable capabilities — your tools, connector actions, and sub-agents — in one uses array on defineAgent (external MCP servers are a separate mcpClients field):

agents/sdr.ts

export const sdr = defineAgent("sdr", {
  connector: openai,
  languageModel: "gpt-4o",
  systemPrompt: "Qualify inbound leads and route hot ones to Slack.",

  uses: [
    enrich, //                                                    your tool (a defineTool handle)
    { ref: scoreLead, description: "Score ICP fit 1–10.", isBulkAllowed: true },
    hunter.actions.findEmail, //                                          an action off a connector handle
    { ref: researcher, waitUntilFinished: true }, //             a specialist sub-agent
  ],

  // External MCP servers whose tools the agent can call (a separate field)
  mcpClients: [{ kind: "custom", name: "notion", url: "https://mcp.notion.com/mcp", authentication: null, disabledToolSlugs: [] }],
});

Each uses entry is a handle — bare, or { ref, …options }. Tools, connector actions, and sub-agents share the options { name, description, isBulkAllowed, waitUntilFinished } (a connector action also takes config, below); the description is the AI contract — the agent reads it to decide when to call the action. A connector action is an action off a defineConnector handle: hunter.actions.findEmail.

Connect an integration with defineConnector before referencing its actions, and see Tools for building the tools you pass in. Run cargo-ai cdk types so a connector handle’s action names (hunter.<action>) autocomplete from the real registry.

How actions work

When an agent receives a task, it:

1. Analyzes the goal and available actions
2. Selects the appropriate action(s) based on their descriptions
3. Executes the action with the right inputs
4. Uses the output to continue reasoning or complete the task

The action’s description is critical. The agent reads this description to decide when and how to use the action. Write descriptions that clearly explain what the action does and when to use it.

---

Configuring an action

Description (the AI contract)

This plain-language description tells the agent:

• What the action does
• When to use it
• What inputs it expects

Good example:

"Enriches a company using its domain. Returns firmographic data including
employee count, industry, funding, and tech stack. Use this when you need
company information for qualification or research."

Poor example:

"Gets company data"

Fixed vs. agent-decided inputs

By default the agent decides every input field of a connector action at runtime, from conversation context and the action’s description. To lock a field to a fixed value, set it in the action’s config — anything you put there is sent as-is and never left to the agent:

uses: [
  { ref: hubspot.actions.createRecords, config: { objectType: "deals" } }, // always deals — the agent fills in the rest
],

Mix fixed and agent-decided fields when some inputs should always be the same (e.g., a specific CRM pipeline ID) while others depend on the conversation context (e.g., a lead’s email address).

In the UI, each field additionally has a mode selector — Default (fixed value), Auto (agent decides), or Disable (field skipped entirely). Disabling a field is UI-only today; in code, fields are either fixed via config or agent-decided.

Bulk execution

Set isBulkAllowed: true when the agent should apply the action across multiple records in a single run. Useful for batch operations like:

• Enriching a list of companies
• Updating multiple CRM records
• Sending notifications to several recipients

Waiting for completion

waitUntilFinished (default true) blocks the agent until the action finishes so it can use the result. Set it to false for fire-and-forget calls — e.g. a Slack notification the agent doesn’t need to read back.

---

Common action types

Category	Examples	Typical use
Enrichment	Clearbit, Apollo, FullEnrich	Gather company or contact data
CRM	Salesforce, HubSpot, Attio	Create/update records, log activities
Communication	Slack, Email, Outreach	Send messages, add to sequences
Data lookup	Internal APIs, SQL queries	Retrieve custom data from your systems

---

MCP servers

Cargo agents support the Model Context Protocol (MCP) — an open standard for connecting AI models to external actions and data sources. Declare the servers an agent can call with mcpClients; Cargo discovers and registers their tools automatically:

mcpClients: [
  // Any MCP-compatible server, by URL
  { kind: "custom", name: "notion", url: "https://mcp.notion.com/mcp", authentication: null, disabledToolSlugs: [] },

  // An MCP server backed by one of your connectors (by uuid)
  { kind: "connector", name: "hubspot", connectorUuid: "9c26…", integrationSlug: "hubspotMcp", disabledToolSlugs: [] },
],

Use disabledToolSlugs to hide individual tools from the agent, and authentication to pass an OAuth token set for servers that require one (or null for unauthenticated servers). In the UI, the same thing is configured by pasting the server URL on the agent’s Actions tab.

This is the agent consuming external MCP servers. To expose your own Cargo tools and agents as an MCP server, see MCP servers.

---

Best practices

Write clear descriptions

The agent relies on descriptions to choose actions. Be specific about what the action does and what it returns.

Name actions descriptively

Use names like Enrich-Company or Slack-Notify-Rep instead of generic names like Action1.

Handle failures gracefully

In your agent’s instructions, specify what to do if an action call fails (retry, skip, report error).

Limit scope

Only give agents access to the actions they need. Fewer actions = faster, more accurate action selection.

---

Next steps

Connectors

Connect integrations with defineConnector before referencing their actions.

Tools

Build reusable tools with defineTool to pass into an agent.