# Give your agent tools

> Add built-in, HTTP API, or remote MCP tools and make their invocation, inputs, and failure behavior clear to the model.

{/* Generated by scripts/sync_docs_handbook.mjs from the preserved in-app docs. */}

A tool lets an agent do more than talk. It can end or transfer a call, get the current time, call a REST endpoint, or invoke a function exposed by a remote MCP server. Menace Voice presents attached tools to the model; the model decides when to call one and which arguments to provide from the conversation.

## Choose the right tool type

- Built-in tools cover Menace Voice behavior such as ending a call, transferring supported telephony calls, calculating a value, or looking up the current time.
- HTTP API tools call a REST endpoint you control or a third-party service. Use them for focused lookups and actions such as finding an order or creating a lead.
- MCP Server tools discover functions from a remote Streamable HTTP MCP endpoint. Use a tool filter and node-level selection to expose only the remote functions the conversation needs.

> **Two different MCP directions**
>
> An MCP Server tool lets a live voice agent call an external MCP server. The Menace Voice MCP endpoint in Agent docs does the reverse: it lets Codex, Claude, or another coding assistant inspect and edit your Menace Voice workspace.

## Define one observable contract

```text
Name: lookup_order
Use when: the caller asks for the current status of a specific order
Required input: order_number (string)
Success result: order status and estimated delivery date
Empty result: say the order could not be found and verify the number once
Failure: say the lookup is temporarily unavailable; never invent a status
```

The name and description help the model decide whether to call the tool. Parameter descriptions tell it what value to extract. Keep each tool focused on one business action, mark only truly necessary fields as required, and return a small structured response the agent can explain naturally.

## Configure an HTTP API tool

- Create a tool and choose HTTP API. Use an action-oriented name and a plain description of exactly when it should run.
- Enter the full endpoint URL, including http:// or https://, and choose the method your endpoint accepts.
- Select a saved credential and add non-secret custom headers when the endpoint requires authentication or routing metadata.
- Define each parameter with a name, type, description, and required flag. Align these with what the endpoint validates.
- Save the tool, open the conversational node that needs it, and attach the tool there. Creating it does not make it available automatically.

## Configure a remote MCP tool

For a remote MCP server, provide the Streamable HTTP URL and the credential required by that server. Bearer Token is the common choice when its documentation specifies Authorization: Bearer. Menace Voice discovers the server's tool catalog when you save or refresh it, then opens a live authenticated MCP session when a call starts.

- Confirm discovery succeeds before attaching the server to an agent.
- Apply a server-level filter when the server exposes functions unrelated to this use case.
- At the node, select only the remote functions that should be callable during that stage.
- Do not place the remote access token in a prompt; the model sees the function schema, not the stored secret.

## Tell the node when to call it

```text
When the caller asks about an order's current status:
1. Ask for the order number if it is missing.
2. Read the number back once for confirmation.
3. Call lookup_order before stating a status or delivery date.
4. If the result is empty or fails, follow the tool's failure instruction.
```

- Test a sentence that should call the tool and one that should not.
- Check the run log for the selected tool, exact arguments, duration, and returned result.
- Exercise invalid input, empty data, authentication failure, and timeout behavior.
- For state-changing actions, confirm the caller's intent before the call and make duplicate requests safe in your backend.

Use [Knowledge & context](/handbook/builders/knowledge) for stable documents and per-call facts; use a tool when the answer must come from a live system or an action must occur.