> ## Documentation Index
> Fetch the complete documentation index at: https://agentheya.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools

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

<Info>
  **Field reference:** [`tools`](/reference/tools) · [`builtin_tools`](/reference/builtin_tools) — every field, type, default, and tier for this page.
</Info>

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](/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).

<Note>
  **Connected-mailbox tools** — once you connect a Gmail or Outlook mailbox under **Sending identity** on the [Email](/sidebar-menu/email-addresses#connect-your-own-mailbox-gmail-outlook) 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.
</Note>

**`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](/reference/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](/reference/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` → `support@acme.com` — 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.

<Note>
  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`.
</Note>

### 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](/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](/custom-tools-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](/builtin-tools/index) section.

## Manage via the Management MCP

This page can be configured programmatically through the [Management MCP](/manage-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`](https://agentheya.com/api/manage-mcp/schema/tools) |

Example:

```json theme={null}
{
  "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.