Creating Tools

A virtual tool is a JavaScript operation attached to an agent. Use it to combine existing connection tools or transform their results into a reusable operation. If one connected tool already does the job, attach that tool directly instead.

Creating Tools with Deco Chat

Describe the outcome, target agent, expected inputs, and connections the operation needs. For example:

Create a support-triage tool for this agent. Read the latest tickets from
our connected help desk, group them by priority, and return each ticket's
ID and original link. Do not change the support records.

The assistant needs access to the relevant management tools. The current workflow is:

1. Identify the agent with COLLECTION_VIRTUAL_MCP_LIST or COLLECTION_VIRTUAL_MCP_GET.
2. Inspect its virtual tools with COLLECTION_VIRTUAL_TOOLS_LIST to avoid duplicates.
3. Create the definition with COLLECTION_VIRTUAL_TOOLS_CREATE: name, description, input schema, JavaScript code, and connection_dependencies.
4. Read it back with COLLECTION_VIRTUAL_TOOLS_GET and test its behavior with representative inputs.

These are management tool names. Ask the assistant to inspect the capabilities available in your workspace rather than assuming an operation is attached to every agent.

What Goes on Under the Hood?

Input schema

Use an explicit JSON Schema for the inputs. Keep fields close to the task domain: a ticket ID, a date range, or a maximum number of records.

JavaScript implementation

Virtual tools use this sandbox signature:

export default async function (tools, args) {
  const result = await tools.some_tool({ id: args.id });
  return { result };
}

tools contains downstream connection tools, not the full agent toolset. Replace some_tool with an actual connected tool. args contains validated inputs matching the declared schema.

Connection dependencies

List the IDs of every connection whose tools the code invokes in connection_dependencies. This lets Studio track those dependencies and surface a broken connection if one is removed.

Output

Return JSON-friendly structured data with a stable shape. Include source record IDs or links when the result needs a person to inspect it.

Discovering Existing Tools

Manage organization integrations under Settings → Connections. Browse the catalog or choose Custom Connection for an MCP server that is not listed. Inside the agent's Settings, select the connections and individual tools it needs. See Connections.

For your own standalone server or an interface backed by a tool, use Building tools and MCP Apps.

Managing Tools

Use COLLECTION_VIRTUAL_TOOLS_GET to inspect a saved definition and COLLECTION_VIRTUAL_TOOLS_UPDATE for a focused change. Keep the declared input schema, code, and connection dependencies in sync. Verify the saved result before testing it again.

Testing

Test the operation on a small, representative input. Check the returned data, original record links, and behavior when a dependency fails. The agent's instructions and selected tools determine the actions it may perform; a virtual tool does not create additional access to external systems.

Implementation reference: virtual-tool guide. Reviewed 2026-10-05.