Skip to content
Caplo DocsDocs

Give an agent tools

Tools let an agent look things up and act in your systems: find an order, check stock, book an appointment. An agent can use two kinds of tools:

  • Tool package tools: code you write and publish in the workspace with the Caplo tool SDK. See Build tools.
  • Remote MCP server tools: tools of an MCP server you connect to the workspace and publish after review. See Connect a remote MCP server.

Both appear in the same list on the agent. A tool must be published before an agent release can use it.

Attach tools

Section titled “Attach tools”
  1. Open the agent and select the Tools & actions tab.
  2. Each tool package and remote MCP server is listed as a group. Check the group to give the agent All tools, including tools added in later versions, or expand it and check single tools.
  3. Select Details on a tool to see its description, input and output schemas, whether it reads or writes, and how it appears to customers.
  4. Select Save draft.

Each group shows how many of its tools are selected, its latest version, and the version the agent’s latest release pins. A tool marked Blocks publishing if selected (for example Build pending) has no usable published version yet; the agent cannot publish while it is selected.

Tool names in agent YAML

Section titled “Tool names in agent YAML”
Form Meaning
<package>/<tool> One tool of a tool package in your project (tools/<package>/caplo.yaml).
<package> Every tool of that project package, including tools added in later versions.
<server>/<tool> One published tool of a workspace remote MCP server, by the server’s name.
<package ID>/<tool> or <package ID> A workspace tool package by its ID. This is the form the console’s Export YAML writes.

Inside a project, a name that is not a project package is looked up as a remote MCP server when you run caplo diff, caplo push or caplo publish. Outside a project, names refer to remote MCP servers, and packages are named by ID. Tool names are lowercase letters, digits and underscores, starting with a letter. An agent can reference at most 32 tools or packages.

How releases pin tool versions

Section titled “How releases pin tool versions”

The draft names packages and tools; it does not name versions. When you publish the agent, Caplo resolves each package to its latest published version and freezes that version into the release, together with each tool’s schema and its read or write effect. A release keeps running the tool versions it was published with, even after the package publishes again. If a pinned tool version is revoked, the release can no longer run it; publish a new release that pins a usable version.

To move an agent to newer tool versions, publish a new release:

  • caplo agent publish <agent> publishes again when the agent’s packages have newer versions, even if the draft has not changed.
  • caplo publish in a project publishes changed packages first, then republishes every agent that uses them.
  • In the console, Publish agent needs unpublished draft changes. The publish dialog lists each tool with the exact version and behavior the release will pin.

Selecting a whole package picks up tools the package adds in later versions at your next publish. Selecting single tools keeps the agent to exactly those tools.

Conversation actions

Section titled “Conversation actions”

The Tools & actions tab also holds the agent’s conversation actions: transfer to a human and ending a voice call. See Handoff and end actions.

Next steps

Section titled “Next steps”