Tools

Overview

Tools are how an agent takes action.

Without tools, an agent can still reason and reply. With tools, it can:

• search

• inspect systems

• call product logic

• trigger workflows

• operate through managed environments such as computer use

• knowledge changes what the agent can know

• tools change what the agent can do

---

A concrete example

Suppose Company A exposes a Platform Support Agent to help Company B troubleshoot a complex rollout.

That agent might need:

• a builtin search tool to search approved internal troubleshooting material
• a custom tool that runs a workflow to validate webhook retries
• computer use for a narrow admin task that cannot be expressed as one clean API call

Tools are not random plug-ins. They are the controlled action surface the agent works through.

---

Built-in tools

Tool key	What it does
search	Search the agent's connected knowledge sources
knowledge_search	Semantic search across indexed documents and data
integrations	Access connected external services (GitHub, Slack, etc.)
long_term_memory	Read and write the agent's persistent memory
artifacts	Create and manage structured output artifacts
task_list	Create and manage task lists and custom objects
skills	Access the agent's linked skill packages
sub_agents	Spawn and manage sub-agent sessions
wait	Pause execution until a condition is met
scheduling	Schedule future work or reminders
computer	Execute commands on the agent's managed computer
images	Process and analyze images

Attach builtin tools to an agent in the CLI or in an AgentTemplate YAML. See Agents for the config format.

---

Inspect the current tool set

Before you add a new tool, inspect the ones the agent already has:

archagent list agenttools --agent <agent_id>
archagent describe agenttool <tool_id>

This is the fastest way to answer:

• which tools are active?
• which are builtin versus custom?
• what handler or config is behind a custom tool?

This is also the review step that tells you whether a tool should be trusted in the first place.

---

Add a builtin tool

Builtin tools are the fastest path when the platform already provides the capability you need.

archagent create agenttool --agent <agent_id> \
 --kind builtin \
 --builtin-tool-key search \
 -k support-search

Then activate it:

archagent activate agenttool <tool_id>

Builtin tools are a good default because they keep the setup smaller and easier to review.

---

Add a custom tool

Use a custom tool when the agent needs a capability that is specific to your workflow or product.

For example, attach a workflow-backed validation tool:

archagent create agenttool --agent <agent_id> \
 --kind custom \
 -n "Validate webhook retries" \
 -d "Checks retry behavior for the acme-billing-webhooks integration" \
 -t workflow_graph \
 --config-id <workflow_config_id> \
 -k validate-webhook-retries

Then activate it:

archagent activate agenttool <tool_id>

That pattern is useful because the workflow stays visible and reviewable, while the agent gets a clean action surface.

---

Add an MCP server

When the capability you need lives behind a remote MCP-compatible tool server (Stripe, Linear, an internal tool server, etc.), add it directly as an MCPServer tool kind. The platform discovers the server's tools at runtime and exposes them to the agent without you defining each one.

tools:
 - kind: MCPServer
 name: stripe-tools
 url: https://mcp.stripe.com/mcp
 auth:
 token:
 secret_value!: <encrypted>

A single MCP server entry can expose dozens of tools. See MCP Servers for the full setup, OAuth and script-based auth modes, and operator workflow.

Review the execution surface before activation

A tool is a privileged capability, not a casual plug-in.

Before you activate one, be clear on:

• what the tool actually does
• what workflow or config it points at
• what systems or data it can touch
• whether the action needs additional approval in your deployment

The docs here describe the operator workflow, not an automatic safety guarantee. The safest pattern is to inspect the tool definition, test it through an embed session or a sandbox, then activate it only when the scope is clear.

For custom tools, that means reviewing the exact workflow or config behind the tool before you trust it in a shared or production-facing flow.

---

Run the tool through an embed session

After the tool is attached, test it through the embed loop from Claude Code or Codex. First install the local plugin from your terminal:

archagent setup

Then invoke embed inside your coding agent:

# Claude Code
/agents:embed

# Codex
$archagents:embed

# Cursor
@archagents embed

This is one of the best operational workflows in the platform:

• attach the tool
• embed the agent
• run the exact capability the live agent would use

This is how you debug the action surface without guessing.

One important limit is worth being explicit about: not every attached tool is directly runnable through the local embed workflow.

• builtin tools only auto-run when they resolve to one concrete callable function
• script-backed custom tools can run directly
• workflow-graph custom tools stay attachable and reviewable, but they are not directly executable through the embed run path

That boundary is useful. It keeps the direct operator loop narrower than the full tool attachment model.

When you use a custom tool, two fields are worth checking first:

• handler_type tells you what kind of execution surface sits behind the tool
• config_id tells you which workflow-backed definition the tool is pointing at

Use describe agenttool whenever you need that detail.

---

Update or pause a tool

Tools are live operational surfaces, so it is important to make state explicit.

archagent update agenttool <tool_id> --description "Updated description"
archagent pause agenttool <tool_id>
archagent activate agenttool <tool_id>

If a tool is misbehaving, pause it before chasing prompt changes. Tool problems frequently get misdiagnosed as agent problems.

---

Best practices

Five rules for working with tools:

1. Start with built-in tools when they already solve the job.
2. Add custom tools only when the business need is real.
3. Back custom tools with visible workflows or narrowly scoped logic.
4. Inspect tool state and handler details before debugging the agent.
5. Test tools through an embed session or a sandbox before broad rollout.

---

Where to go next

1. Read MCP Servers for connecting to remote tool servers.
2. Read Skills for reusable coding-agent behavior linked to agents.
3. Read Embed for the best local testing loop.
4. Read Computer Use when the capability needs a managed workstation instead of a simple tool call.
5. Read Field Guards when an agent's structured tool output needs content policy enforcement.