Troubleshooting tool errors
Common failures when configuring or running API Request and MCP tools — and where to look next.
Quick diagnosis
Section titled “Quick diagnosis”| Symptom | First check |
|---|---|
| Tool never called | Assistant has tool attached; description mentions when to use it |
| 401 Unauthorized | Credential type and expiry |
| 404 Not Found | URL and path params |
| 400 Bad Request | Body schema vs API contract |
| ”Invalid parameters” | Strict params — fix schema or descriptions |
| No carousel/cards | Transform and trust policy |
| MCP connection failed | Transport and server URL |
| Slow chat | Execution mode; add status notifications |
Auth issues
Section titled “Auth issues”- Re-test credential in Credentials → Test (if available).
- Confirm Bearer vs API key header name.
- For OAuth, re-authorize in OAuth 2.0 settings.
- See dedicated 401 troubleshooting.
Parameter issues
Section titled “Parameter issues”- Path placeholder names must match param names exactly (
{order_id}↔order_id). - Query param types must match API (integer vs string dates).
- Improve descriptions so the model asks visitors for the right format.
Rich content issues
Section titled “Rich content issues”| Issue | Fix |
|---|---|
| Empty carousel | Verify items_path on real test response |
| Wrong price field | Update fields.price path in transform |
| Cards on failure | Should not happen — check logs for spurious 200 empty bodies |
MCP-specific
Section titled “MCP-specific”- Verify server exposes tools over the correct transport.
- Check firewall allows Chatevo egress to your MCP URL.
- Review execution logs for handshake vs tool-level errors.
Still stuck?
Section titled “Still stuck?”- Capture a failed run from logs (redact PII).
- Compare with a successful curl test to your API.
- Contact support with tool ID and timestamp.