Best Practices

Documentation Index

Fetch the complete documentation index at: https://docs.clarityq.ai/llms.txt

Use this file to discover all available pages before exploring further.

These tips will help you get better results from ClarityQ — whether you’re asking your first question or running complex analyses daily.

​

Asking Questions

​

Be concise and intentional

Translate business questions into clear analysis questions. The clearer the question, the better the analysis.

​

Ask ClarityQ how to investigate your problem

If you’re unsure where to start, ask ClarityQ what questions you should ask. For example: “I see a drop in revenue per user over the last 4 weeks. What should I ask to get the most accurate analysis?”

​

Split complex questions into smaller ones

Break down big or multi-part questions and use follow-ups. This helps ClarityQ reason more effectively and reduces confusion.

​

Using the Semantic Layer

​

Reference semantic layer components with @mentions

Prefer metrics and segments from the Semantic Catalog. Type @ and select from the popup to ensure consistency and correctness across your analyses.

​

Managing Conversations

​

Start a new session when changing context

If you move to a different problem or business area, start a fresh chat to avoid context bleed from previous questions.

​

Use Edit when you want to refine, not restart

Edit is best for small corrections — clarifying a question, adjusting a filter, fixing wording, or changing a metric. No need to start over for minor changes.

​

Turn off visualizations unless needed

Save tokens and focus on reasoning first. Enable charts only when you need to visualize results.

​

Validating Results

​

Validate complex results

ClarityQ improves constantly, but no system is 100% accurate. Always sanity-check complex queries and conclusions.

​

If something looks odd in a visualization, say it

Tell the agent what seems wrong and ask it to fix, explain, or regenerate the visualization.

​

Challenge results that don’t make sense

You can investigate further, disagree with the agent, and ask it to re-check assumptions or analyze the data from a different angle.

​

What’s Next?