> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ada.cx/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server.

# Troubleshooting

> **Tip**
>
> **Not sure where to begin?** Explore our [Getting started](/docs/welcome/getting-started) guidelines to set up your first AI Agent, review [Key concepts](/docs/welcome/key-concepts) to understand the essentials, or check out [Improvement tactics](/docs/welcome/improvement-tactics) to resolve issues and keep things running smoothly.

## Common questions

If an MCP tool isn't behaving as you expect, the cause is usually discovery, the auth mode, the connection, or a Playbook mapping. Here's how to resolve each.

* **A tool you added on your server isn't listed yet.** New tools appear after you refresh the tool list on the **Tools** page. Refresh, then turn the tool on.
* **You want the Agent to choose a different tool.** The Agent picks a tool from the name and description your server declares, so clear, specific descriptions guide it to the right one. If an API tool covers the same job, turn one of them off so there's a single clear choice.
* **A customer sign-in tool works on some channels but not others.** Tools that ask the end user to sign in run on Ada Chat, Twilio SMS, Twilio WhatsApp, Ada Instagram, and most Zendesk Sunshine Conversations channels. On other channels the Agent answers without them, so use a connected-account tool where you need coverage everywhere. See [Authentication and channels](/docs/automation/tools/mcp-tools/authentication-and-channels).
* **An end user is asked to sign in when you didn't expect it.** That tool is set to **customer signs in**. If it doesn't need a person's own data, switch it to **connected account** so it runs on the shared company account.
* **A connection needs reconnecting.** Sign-in credentials refresh as tools are used. If a connection has been idle and its sign-in has lapsed, reconnect the server from the **Tools** page to restore its tools.
* **Setting up an OAuth connection.** If your server limits which redirect URLs it accepts, add Ada's redirect URL so the sign-in completes. The connect form shows the URL to add.
* **A Playbook variable is empty.** Check the path against what the tool returns: JSON lets you pull one value by path, and plain text is captured whole. Run the tool in a conversation, read the result, and map from what you see.

## Related features

* [Connect a server](/docs/automation/tools/mcp-tools/connect-a-server): Add a server, give it a credential, and turn on its tools.
* [Authentication and channels](/docs/automation/tools/mcp-tools/authentication-and-channels): Connected account vs. customer sign-in, and channel support.
* [Limits and best practices](/docs/automation/tools/mcp-tools/limits-and-best-practices): Choosing safe tools and writing good descriptions.

---

Have any questions? Contact your Ada team, or email us at [](mailto:help@ada.cx?subject=Help%20Docs%20inquiry).