Tools

Tools let an agent do more than answer with text: check an order’s status, look up a customer in your CRM, create a ticket, or read a Google Drive file. The model decides when to call a tool from its name and description.

There are three kinds, each under Build in the sidebar:

Kind	Where	What it is
Custom tools	Tools	An HTTP endpoint of yours, described so the agent can call it.
Predefined tools	Predefined Tools	Built-in capabilities that ship with VirtuAI.
MCP servers	MCP Servers	Tools from a server that speaks the Model Context Protocol, including ready-made Google, GitHub, Slack and HubSpot servers.

A tool does nothing until it is attached to an agent. Attach tools, predefined tools and MCP servers in the agent’s visual canvas.

Custom tools

Open Tools and select Add tool.

Basic Information

Field	What it does
Tool Name	Required. The name the model sees, for example get_order_status. Letters, numbers, underscores and hyphens, up to 128 characters.
LLM Description	Required. Tells the model what the tool does and when to call it. Not shown to users.
Visual Description	Optional. A short, user-facing description shown in tool lists. Up to 180 characters.

API Configuration

Field	What it does
API Endpoint	Required. The URL to call. It can contain parameters, for example https://api.example.com/orders/{{order_id}}.
HTTP Method	GET, POST, PUT, DELETE or PATCH.
Timeout (seconds)	1 to 300. Default 30.
Headers (JSON)	Headers sent with every call, as a JSON object. Values can contain parameters in the same {{name}} form.
Authentication	None, or Google Cloud Run (IAM / Service Account).

With Google Cloud Run (IAM / Service Account), VirtuAI signs each call with an identity token for the endpoint’s host, using the Cloud Run service account saved in Workspace settings as CLOUD_RUN_SERVICE_ACCOUNT_JSON. Grant that service account the Cloud Run Invoker role on the target service.

Caution

Header values are stored with the tool, and anyone who can edit tools in the workspace (tools.edit) can read them. People who can only view tools see the header names, with the values masked. Prefer Cloud Run IAM authentication, or a key scoped to exactly what the tool needs.

Parameters

Parameters are the inputs the model fills in when it calls the tool. Select Add Parameter for each one.

Field	What it does
Name	The parameter name, for example order_id.
Type	string, integer, number, boolean, array or object.
Description	What the value is and its format, for example “Order number, such as ORD-1234”. The model reads this.
Required	Whether the model must always provide it.

How parameters are sent:

• A parameter written into the endpoint or a header as {{name}} is substituted there.
• The remaining parameters go in the query string for GET and DELETE, and in a JSON body for POST, PUT and PATCH. For a JSON body, Content-Type: application/json is added unless you set it yourself.

The Preview card shows the method, endpoint, timeout and parameter names as you type.

What the agent receives

• A JSON response is passed to the agent as is. Any other response is passed as text.
• An HTTP error (status 400 or above), a timeout or a connection failure reaches the agent as an error message it can explain or recover from. Tools created from this form are not retried on failure.
• If your API is used by the web voice widget, it can also return data for the widget to display.

Writing good tools

The model decides when to call a tool, and with what, from its name, description and parameter descriptions. Be explicit:

• Say what the tool does and when to use it, for example “Use when the customer asks where their order is”.
• Describe each input and its format, with an example.
• Describe what comes back, including the error cases.
• Keep one action per tool. get_order and cancel_order are easier to use correctly than one order tool with a mode switch.

Test each tool in chat before the agent goes live, including a call where the tool fails. To catch an agent that answers without calling the tool, add the tool to an evaluation case with the tool_trajectory scorer.

Predefined tools

Predefined Tools lists the built-in tools. You can’t change what they do; the pencil icon edits the Visual description for users shown in tool lists (up to 180 characters).

Tools	What they do
reminder_tool, list_reminders_tool, delete_reminder_tool	Create, list and delete reminders for the current conversation, one-off or recurring (daily, weekly or monthly). Reminders work in Google Chat; on other channels the agent tells the user they are not supported.
builder_*	Create and configure agents, tools, knowledge bases, MCP servers and evaluation datasets. They power the Agent Builder.
browser__*	Drive a Chrome browser: navigate, search, click, type, scroll, fill forms, extract content, take screenshots and save pages as PDF. They need a browser session connected through the VirtuAI CLI.

Caution

The builder_* tools let an agent create and change other agents in your workspace. Attach them only to agents that workspace admins use.

MCP servers

The Model Context Protocol (MCP) is an open standard for exposing tools to AI agents. An MCP server added to your workspace can be attached to any agent, and its tools become the agent’s tools.

Open MCP Servers and create a server. Choose Predefined or Custom.

Predefined servers

Ready-made servers where each user signs in with their own account:

Group	Servers
Google Workspace	Gmail, Google Drive, Google Calendar, Google Chat, Google Contacts
Google Cloud · Data & Analytics	BigQuery, Pub/Sub, Firestore, Bigtable, Dataproc (Managed Spark)
Google Cloud · Storage & Compute	Cloud Storage, Compute Engine, Cloud Run, Google Kubernetes Engine, Memorystore (Redis)
Google Cloud · Databases	Cloud SQL, AlloyDB, Cloud Spanner, Database Center
Google Cloud · Observability	Cloud Logging, Cloud Monitoring, Cloud Trace, Error Reporting
Developer Tools	GitHub
Communication	Slack
CRM	HubSpot

1. Enter a Server Name (letters, numbers, underscores and hyphens, up to 128 characters) and a Description.
2. Select the service. The form lists the Required OAuth Scopes.
3. Select Create Server and attach the server to an agent.

Before users can connect, a workspace admin must add the OAuth client for the provider in Workspace settings:

Provider	Settings
Google	GOOGLE_MCP_CLIENT_ID, GOOGLE_MCP_CLIENT_SECRET, GOOGLE_MCP_REDIRECT_URI
GitHub	GITHUB_MCP_CLIENT_ID, GITHUB_MCP_CLIENT_SECRET
Slack	SLACK_MCP_CLIENT_ID, SLACK_MCP_CLIENT_SECRET
HubSpot	HUBSPOT_MCP_CLIENT_ID, HUBSPOT_MCP_CLIENT_SECRET

For Google, create a Web application OAuth client in the Google Cloud console and register the redirect URI there, for example https://yourdomain.com/api/oauth/google/callback.

Users then connect their own account from the agent’s tools menu in web chat. Each user’s token is stored separately, so the agent acts with the permissions of the person it is talking to, and one consent covers every service from the same provider.

Custom servers

For any other MCP server, paste its connection as JSON under Configuration (JSON). Three transports are supported: streamable_http, sse and stdio.

A remote server over HTTP:

{
  "transport": "streamable_http",
  "url": "https://mcp.example.com/mcp",
  "headers": { "Authorization": "Bearer YOUR_TOKEN" }
}

A server started as a command:

{
  "transport": "stdio",
  "command": "npx",
  "args": ["@some/mcp-server"],
  "env": { "API_KEY": "..." }
}

Choose which tools an agent sees

After the server is saved, open it again and select List tools to see what it offers. By default every tool is available to agents. Untick the ones you don’t need, or use Enable all and Disable all, then Save Changes.

Each tool’s definition is sent to the model on every turn, so disabling unused tools saves context and makes the right tool easier to pick. If the list was fetched without an authorized account, some servers return fewer tools; connect the integration and select Refresh.