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

# Function Calling & Tools

> Give your AI agents tools to act during calls. Book appointments, update your CRM, send confirmations, and end calls gracefully.

## What Is Function Calling?

Function calling lets your AI agent execute actions during a call. Instead of just talking, your agent can:

* Book appointments in your calendar
* Look up orders in your systems
* Update CRM records
* Send confirmations
* End the call gracefully when the conversation is complete

<CardGroup cols={2}>
  <Card title="Real-Time Action" icon="plug">
    The agent invokes tools mid-conversation and uses the results in its next reply.
  </Card>

  <Card title="Natural Experience" icon="user-check">
    Callers don't notice the tool call. It feels like talking to an agent who has your systems open in front of them.
  </Card>

  <Card title="No-Code or Your Own Server" icon="puzzle-piece">
    Build tools visually in the Integrations platform, or connect your own MCP server through the API.
  </Card>

  <Card title="Explicit Opt-In" icon="shield-check">
    Only tools you allowlist are available to the agent. Nothing attaches by default.
  </Card>
</CardGroup>

## Built-in Tools

TopCalls provides built-in tools that are automatically available during calls.

### end\_call

The `end_call` tool allows your AI agent to gracefully end the call when the conversation is complete.

<Note>
  The AI uses `end_call` automatically when appropriate. The agent decides when to end based on context: user says goodbye, all questions answered, or clear conversation conclusion.
</Note>

**When the AI uses end\_call:**

* User says "goodbye", "thanks, that's all", etc.
* All questions have been answered
* User explicitly asks to end the call
* Conversation naturally concludes

**What happens:**

1. AI decides to end the call
2. AI speaks a contextual farewell message
3. Call is terminated

<Tip>
  You can influence end-call behavior in your instructions: "Always confirm the next steps before ending the call" or "Offer to help with anything else before saying goodbye."
</Tip>

## Custom Tools

There are two ways to give the agent custom tools.

### Through the Integrations Platform (No Code)

Build a flow in the Integrations platform (for example "book a callback in Google Calendar" or "send an SMS confirmation"), then select it as a tool in the campaign editor. During calls, the agent can invoke the flow and use its result in the conversation. See [Integrations](/integrations) for the full catalog of connectable tools.

### Through Your Own MCP Server (API)

If you run your own tool server that speaks the [Model Context Protocol](https://modelcontextprotocol.io), connect it per call:

```json theme={null}
{
  "phone_number": "+14155551234",
  "instructions": "You are Rachel, an appointment coordinator...",
  "mcp_url": "https://tools.your-app.com/mcp/abc123",
  "mcp_token": "YOUR_MCP_BEARER_TOKEN",
  "mcp_tool_allowlist": ["check_availability", "book_appointment"],
  "tool_call_timeout_ms": 3000
}
```

| Field                  | What it does                                                                                              |
| ---------------------- | --------------------------------------------------------------------------------------------------------- |
| `mcp_url`              | Your MCP server URL. The gateway connects at call start and merges your tools into the agent's tool list. |
| `mcp_token`            | Bearer token the gateway sends to your server. Redacted from logs.                                        |
| `mcp_tool_allowlist`   | Names of the tools the agent may invoke. When absent or empty, no remote tools are attached.              |
| `tool_call_timeout_ms` | Per-invocation timeout (500 to 10000 ms, default 3000).                                                   |

<Warning>
  The allowlist is an explicit opt-in. Listing your server with `mcp_url` alone attaches zero tools; name each tool the agent should have. This keeps the prompt small and the agent focused.
</Warning>

## How a Tool Call Works

<Steps>
  <Step title="1. AI Decides">
    During the conversation, the AI decides a tool is needed based on what the caller asked.
  </Step>

  <Step title="2. Invocation">
    The gateway invokes the tool with the arguments the AI chose.
  </Step>

  <Step title="3. Result">
    The tool's result is fed back to the AI.
  </Step>

  <Step title="4. Response">
    The AI works the result into its next reply and the conversation continues.
  </Step>
</Steps>

```
User: "Can you check if 3 PM tomorrow is available?"

AI: [Invokes check_availability with date and time]
    → Tool returns: {"available": true}

AI: "Yes, 3 PM tomorrow is available! Would you like to book it?"
```

## Error Handling

If a tool call fails or times out, the AI is told and recovers conversationally:

> "I'm having trouble reaching the calendar right now. Can I take your preferred time and have someone confirm it shortly?"

Design your tools to return clear error messages; the AI relays the situation naturally instead of exposing raw errors to the caller.

## Best Practices

### Do This

* **Clear names and descriptions**: The AI picks tools based on their descriptions, so write them precisely
* **Validate inputs**: Always validate arguments on your side before acting on them
* **Return structured data**: Use consistent response formats
* **Fast responses**: Return results quickly (under 2 seconds) so the conversation stays natural
* **Allowlist narrowly**: Give the agent only the tools this call needs

### Avoid This

* **Vague descriptions**: "Helper function" doesn't help the AI decide when to use it
* **Slow tools**: Long tool calls create awkward silence on the line
* **Too many tools**: Limit to 5-10 tools per call for best results
* **Secrets in prompts**: Keep credentials on your server, never in instructions

## Next Steps

<CardGroup cols={2}>
  <Card title="Integrations" icon="puzzle-piece" href="/integrations">
    Build no-code tools and flows for your agent.
  </Card>

  <Card title="Making Calls" icon="phone" href="/guides/making-calls">
    Learn how to include tools when making calls.
  </Card>
</CardGroup>