Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.copass.com/llms.txt

Use this file to discover all available pages before exploring further.

The tools an agent can call at runtime aren’t pinned at create-time — they’re resolved dynamically from the sandbox’s connected data sources. Connect a new Slack integration, and every agent in the sandbox sees Slack tools next time they run. Disconnect it, they don’t. Two stacked controls decide what an agent actually sees:
ControlSourceEffect
tool_sourcesAgent rowWhich resolvers compose at all (copass_retrieval, pipedream, user_mcp, …)
tool_allowlistAgent rowWhich tool names are callable from those sources. [] = all allowed
tool_sources controls the resolvers. tool_allowlist controls the names. Both are JSON columns on the agent row; the Concierge can update either.

​
What you can do

  • Inspect the live tool catalog an agent will see at runtime.
  • Tighten an agent’s allowlist to specific tool names.
  • Add or remove tool sources (e.g. enable a custom MCP source, disable Pipedream).
  • Audit why an agent saw the tools it saw on a specific run.
“What tools does my support agent have right now?” “Lock the support agent to only the Slack and GitHub tools.” “Add my custom MCP server’s tools to the triage agent.” “Why didn’t my agent use any tools on that last run?”
The last one pulls the run’s tool-resolution trace and points to whichever gap (allowlist drift, missing source, missing OAuth) caused the silent no-op.

​
Via the CLI

# Inspect what's currently resolvable in a sandbox
copass agent tools                         # all dynamic tools
copass agent tools --app slack             # filter by app

# Tighten the allowlist
copass agent update support \
  --tool-allowlist '["pd_slack_v2_slack_v2-add-reaction","pd_github_github-list-issues"]'

# Switch tool sources
copass agent update support \
  --tool-sources '["copass_retrieval","pipedream"]'

​
Via the SDK / API

// Inspect the live catalog
const catalog = await client.agents.listTools(sandboxId, { app: 'slack' });

// Update sources / allowlist
await client.agents.update(sandboxId, 'support', {
  tool_allowlist: ['pd_slack_v2_slack_v2-add-reaction', 'pd_github_github-list-issues'],
});

​
Naming conventions

Tool names are stable wire identifiers. They appear in the agent’s tool_allowlist, in the run’s tool-resolution trace, and in the model’s catalog at runtime.
SourceName shapeExample
Pipedream integrationspd_<app_slug>_<remote_tool_name>pd_slack_v2_slack_v2-add-reaction
Copass retrievaldiscover / interpret / search(built-in)
Custom MCP<source_label>_<remote_tool_name>internal_mcp_lookup_customer
Mandatory: always inspect the live catalog before writing an allowlist. Hallucinated tool names get filtered out at resolution time — agents with bad allowlists run tool-less and silently no-op.

​
Diagnosing “agent did nothing”

Most “my agent fired but didn’t use tools” issues fall into three buckets:
  1. Allowlist drift — a tool the allowlist names doesn’t exist anymore (renamed, integration disconnected). Filtered out, agent runs tool-less.
  2. Missing OAuth — the integration was disconnected; no resolver builds, no tools advertised.
  3. Source not in tool_sources — you connected Slack but the agent’s tool_sources doesn’t include pipedream.
The Concierge’s run-trace tool (get_run_trace) surfaces all three explicitly. From the CLI: 
copass agent runs support              # find the run id
# then ask the Concierge: "Why did run <run_id> not use tools?"

​
Common patterns

Open while iterating, locked at ship

Develop with tool_allowlist: []. When the agent is stable, snapshot the actually-used tool names and lock to that list.

Inspect before allowlisting

Always run agent tools (or “what tools does X have?”) before writing an allowlist. Names are exact.

Per-source tool sets

A retrieval-only agent can drop pipedream from tool_sources entirely. Smaller catalog = better selection accuracy.

Custom MCP for private tools

Internal APIs your agent should call: wrap them in an MCP server, register as user_mcp, and they show up in the catalog. See Custom MCP.

​
Next steps