Describes troubleshooting information for errors that can occur while using iQ Studio.
Incorrect or incomplete system prompt, user input, or tool outputs
- Open the full LLM payloads in Debug Mode. Compare the system prompt, user message, and tool outputs to your expected values.
- Verify that the runtime assembled these components correctly.
- Update the system prompt or tool descriptions as needed.
- Confirm that the correct knowledge collections, database rows, or tool configurations are attached.
- Rerun the query in Debug Mode to validate the fix.
The model ignored key instructions or lacked reasoning transparency
- Review the raw LLM output in the debug payload to see the model’s unprocessed reasoning.
- Look for signs that the model misunderstood instructions or skipped key parts of the prompt.
- Clarify or strengthen instructions in the system prompt.
Missing or incorrect context was passed to the model
- Look for evidence of:
- Missing context, such as knowledge snippets not included.
- Tool outputs not passed correctly.
- Parameters summarized incorrectly in Agent Thoughts.
- Recheck tool configurations in the MCP Tool Library.
- Confirm that the agent is using the intended knowledge collections or tool settings.
- Rerun the query with Debug Mode on to verify that context now appears.
Agent configuration issues
- Compare the LLM prompt against tool outputs to ensure they were combined correctly.
- Identify mismatches such as missing fields, misaligned data, or skipped steps.
- Modify the agent prompt, reconfigure tools, or adjust wiring.
- Debug Mode is explicitly designed to reveal these issues.
The agent returns no results or an error message
- Confirm the database connection URL is valid and the database is reachable from the iQ Studio environment.
- Verify that the DB MCP tool is attached and shows as active on the agent's Equip page.
- Re-enter the database URL and click Apply to refresh the connection.
The SQL statement shown is incorrect or produces wrong results
- Review the generated SQL statement displayed in the response.
- Rephrase the natural language query to be more explicit (for example, specify column names or date ranges).
- Consider switching to a specialized SQL translation model if available.
The agent does not display the SQL statement used
- Confirm that the DB MCP server is configured to return query evidence alongside results.
- Check whether the system prompt instructs the agent to show its SQL output. Update the prompt if needed.
Analytical summaries are incomplete or missing data
- Confirm that the database contains the expected data range (1988–1991 flight records).
- Verify that the agent has permission to execute multiple sequential queries within a single session.
- Re-run the query and check whether partial results are returned that indicate a timeout or row limit issue.