Prompting guide¶

AIVA is the first agentic variant analysis platform. It translates your natural language questions into tool calls, SQL queries, and structured analysis. The quality of your results depends on how you frame your questions. This section covers practical strategies and worked examples drawn from real analysis workflows.

Best practices¶

Be specific about what you want¶

Vague prompts produce vague answers. Include gene names, frequency thresholds, consequence types, and sample identifiers in your questions. The more context you give AIVA, the more precise and actionable the results.

Ask for counts before listing¶

For large datasets, asking AIVA to list all matching variants can produce overwhelming output. The chat displays up to 100 results at a time, so starting with a count helps you decide whether to list everything, add more filters, or export the results.

Example workflow:

"How many variants in @samples:family_cohort have a gnomAD allele frequency below 0.001 and a DITTO score above 0.8?"

Then follow up:

"List those variants, sorted by DITTO score descending."

Chain your prompts¶

AIVA maintains conversation context across messages. You can build up your analysis step by step rather than asking one massive question. Each follow-up benefits from the context of previous answers.

Example prompt chain:

1. "How many samples in @samples:cohort_40 carry rare variants in SCN1A?"
2. "Which specific samples have those variants?"
3. "For sample HG003, list the SCN1A variants with their consequence and allele frequency."
4. "Classify the most significant variant using ACMG criteria."

Reference your data explicitly¶

Use the @ mention to tell AIVA which dataset to query. Without it, AIVA may not know which sample you mean. You can reference multiple samples in a single prompt.

Referencing specific files:

• @samples:clinical_data to query your clinical metadata
• @samples:multisample_vcf to query a multi-sample VCF
• @samples:sample1, @samples:sample2 to reference multiple individual samples

Quick reference¶

1. Attach your data: Type @ and select your sample before asking questions about it.
2. Be specific: Include gene names, frequency thresholds, consequence types, and sample identifiers.
3. Filter for quality: Ask AIVA to filter for PASS status and minimum read depth to exclude artifacts.
4. Count first, list second: Ask for counts before requesting full variant lists.
5. Chain prompts: Build analysis step by step. AIVA remembers conversation context.
6. Cross-reference datasets: Query clinical data first to establish context, then query variants.
7. Match your model to the task: Use faster models for simple queries and more capable models for multi-step analysis.

In this section¶