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

# Troubleshoot Thoughtly voice agents

> Diagnose and resolve common voice agent issues including audio quality, transfers, action failures, prompt drift, and unexpected hang-ups in Thoughtly.

## Common Issues

### Agent Not Responding as Expected

If your agent isn't responding correctly:

* Review your agent's configuration in [Settings](/agents/settings)
* Check [Outcomes](/agents/outcomes) and [Variables](/agents/variables) setup
* Verify node connections in the agent builder
* Test with simple conversations first using [Test Agent](/agents/testing)

### Call Quality Issues

For call quality problems:

* Check internet connection stability
* Verify phone number configuration in [Phone Numbers](/phone-number/configuration)
* Review the [Settings](/agents/settings) including voice and presence tuning
* Test with different voice options from the [Voice Selector](/agents/voices)

### Agent Not Following Node Flow

If your agent isn't following the intended conversation flow:

* Verify all nodes are properly connected
* Check outcome conditions and logic
* Review the [Nodes](/agents/nodes) documentation
* Test each branch of the conversation separately

### Variable Issues

For variable-related problems:

* Ensure variables are properly defined
* Check variable scope and availability
* Review the [Variables](/agents/variables) guide
* Verify data is being passed correctly

### Special Characters in Call Transcripts

If your agent is pronouncing special characters (asterisks, underscores, brackets, etc.) during calls:

The LLM may be generating speech-like markdown that includes special characters. To resolve this, add the following instructions to your agent's **Advanced Prompt** (not individual speak nodes):

```
You are writing text for TTS; special characters like *, _, #, [, ], (, ), etc. must never appear.
Never output special characters under any circumstance.
If input contains special characters, remove them and rewrite naturally.
If you need to refer to a special character, spell out its name (e.g., "asterisk", "underscore").
```

This ensures the instruction applies to the entire agent and prevents special characters from appearing in the call transcript or being pronounced by the TTS system.

For additional assistance, visit our [Support Center](/support/getting-help).