Tools

Define callable tools your agent can invoke — API endpoints, code functions, or built-in operations.

Field reference: tools · builtin_tools — every field, type, default, and tier for this page.

Tools are the actions your agent can take during a conversation. When the agent decides it needs external data or to perform an operation, it calls a tool, receives the result, and incorporates it into its response. Tools can call HTTP APIs, execute code, or trigger built-in platform operations.

The dashboard page has two main sections: Built-in tools (toggle each on or off, and optionally wrap one to preset its parameters) and Custom tools (the tools you define yourself).

Built-in tools

Built-in tools ship with the platform. Each one has an on/off toggle; Enable all and Disable all affect the whole list. The available built-ins include:

Tool	Description
web_search	Searches the web and returns results.
web_fetch	Fetches a URL and returns the content as markdown.
calculate	Evaluates math expressions.
execute_code	Runs Python or JavaScript in a sandbox.
send_email	Sends email via the configured provider.
check_email_status	Looks up delivery status for a previously sent email.
present_public_file	Shows a download card for a public file.
show_file_excerpt	Quotes a line range from a public text file.
show_image	Renders an image from public data inline.
surface_file	Generates and shares a file for the user to download.
confirm_action / commit_action	Two-step confirmation flow before destructive actions.
collect_form	Renders a form and waits for the user to submit it.
render_ui	Renders generative-UI components inline (see Generative UI).
request_human_handoff	Escalates to a human via the configured handoff channel.
delegate_to_agent	Single-shot Pattern 1 call to a peer agent.

Some built-ins depend on an integration being configured. Until then they appear with a muted Not connected badge, can’t be toggled on, and auto-enable the moment their integration is set up (for example, the X / Twitter and Obsidian tools).

Connected-mailbox tools — once you connect a Gmail or Outlook mailbox under Sending identity on the Email page, a set of gmail_* / outlook_* tools appears in this list (search and read messages, send or draft as that real identity, and label / organise messages) and acts on the connected account. Memory tools (read/write persistent information about the user) toggle from the Memory page, not here.

web_search engine (owner only) — the web_search tile has an Engine selector: the platform’s built-in search (Internal) or Anthropic’s native web_search. With the Anthropic engine, an Options panel exposes its parameters (max uses/results, topic, allowed/blocked domains, user location).

Outbound recipients (owner only) — the Allow open email/IM recipients in subscriber chats toggle controls where send_email and im_send may deliver in subscriber and inbound sessions. Off (recommended): the agent may only email the user’s own verified address (or reply to mail they sent), and im_send is disabled — this blocks prompt-injection abuse of your verified email domain and IM bots. On: the agent may message any recipient in those sessions. Your own preview chats are never restricted.

Wrapping a built-in tool

Some built-ins are wrappable — click Wrap Built-in Tool to create a custom-named variant of the base tool with some of its parameters pre-set. The wrapped tool appears to the LLM as its own tool, with your presets baked in. For each parameter you can pick one of three override modes:

Mode	Label in the editor	What the agent sees
Lock	Lock (hidden)	The value is fixed and the parameter is removed from the tool schema entirely — the agent can’t set or even see it.
Default	Default (overridable)	The value is pre-filled but the parameter stays visible; the agent may override it.
Append	Append to agent value	Your value is concatenated onto whatever the agent supplies.

The wrap editor also has a Parameter guards section (validation rules) and can Block the tool entirely — see Tool Guards.

You don’t have to wrap a tool to guard it. The Tool Guards button on the Wrap Built-in Tool card opens a dialog where you can add validation/transform rules — or Block it outright — for any tool by its runtime name: a built-in by its plain name (web_search), a custom tool as tool_<name>, or an MCP/connector tool by its namespaced name. See Tool Guards.

Simple — a zero-argument “download this report” tool. Wrap present_public_file and lock filename to your report’s exact name. The result is a tool the agent can trigger but can’t redirect — it always downloads that one report, with no arguments to get wrong.

All three modes together — a scoped support-email tool. Wrap send_email as notify_support_team:

• Lock to → [e-mail] — hidden from the agent entirely, so it can only ever email that address.
• Default subject → "Escalation from agent" — the agent may override it when a more specific subject fits.
• Leave body_text on Agent decides (no override) so the agent writes the message body.

Custom tools

Custom tools let you define your own actions. Click Add Tool in the Custom tools section. Each custom tool has a type:

Type	Description
api_endpoint	Calls an HTTP endpoint. The agent passes arguments as a JSON body or query string.
code	Runs a Python or JavaScript function in a secure sandbox. Language is auto-detected from the code.
derived	A wrapped built-in tool (created via Wrap Built-in Tool).

Common fields

Field	Description
Name	Tool identifier (letters, digits, underscores; must start with a letter).
Description	Tells the LLM when and how to use the tool.
Input schema	Parameters the agent collects before calling. Each has a name, type, description, and required flag.
Visible to user	Whether the tool’s existence and arguments are surfaced in the chat UI when called.
Result note	Optional hint shown to the LLM with every tool result.

Owner tools, subscriber tools, and Author tools

Custom tools come in three flavours depending on who created them and where you’re looking:

• Owner tools — the tools you (the agent owner) define in the Custom tools section. Each has a Visible to user toggle: when on, subscribers can see it on their own Tools page and disable it for themselves (they can never edit it).
• A subscriber’s own tools — on their personal Tools page, a subscriber can create their own custom tools, fully separate from yours and scoped to their sessions.
• Author tools — on a subscriber’s Tools page, your visible owner tools appear in a read-only Author tools card (“Tools created by the agent’s author”). The subscriber can toggle each on or off for themselves but cannot edit them.

API-endpoint tools

Set Method (GET/POST/PUT/DELETE), Endpoint URL, and any headers. The agent’s arguments are sent as a JSON body for write methods or as query parameters for GET.

Code tools

Paste a Python or JavaScript function body. The language chip below the editor shows what was detected.

Code tools run in a secure sandbox with hard limits: 30 s per call, 256 MB memory, 1 MB output, and up to 50 ctx.tools cross-calls per invocation. Python ships the standard library plus httpx, requests, numpy, pandas, beautifulsoup4, lxml, Pillow, markdown, and pydantic.

Worked examples and the result contract

For the contract governing what a tool returns to the agent vs. what it shows the user — returning a _render payload (with _interactive: true for clickable renders) — and the full catalogue of UI components your tools can render, see Generative UI. For the handle(input, ctx) signature and the ctx.tools.<name>(...) bridge that lets your code call built-in tools, see Custom tool ctx.

Tool call visibility

Tool calls appear in the activity log and in conversation traces. You can inspect the inputs and outputs the agent used for any call.

For deeper detail on each built-in, see the Reference section.

Manage via the Management MCP

This page can be configured programmatically through the Management MCP — useful for AI agents and CI pipelines.

Endpoint	https://manage.agentheya.com/mcp
Tool	config.set
Section	tools
Schema (HTTP)	GET /api/manage-mcp/schema/tools

Example:

{
  "tool": "config.set",
  "owner_id": "<your owner_id>",
  "agent_id": "<your agent_id>",
  "section": "tools",
  "data": { /* see schema for accepted fields */ }
}

Partial updates are supported — only the fields you include are changed. Call config.get to read the current values and schema.get (or the HTTP schema URL above) to see the full field list.