use-existing-viz

name	use-existing-viz
description	Search and use visualizations that already exist in the project to provide fast and curated data answers.

Pre-requisites

• Set up Holistics MCP

Context

• "viz" or "viz blocks" refer to visualization blocks defined in Dashboards (.page.aml files)

Search for existing viz

When to search

• When a user asks a data question that requires querying data, call search_viz_blocks first to find reusable viz blocks before generating new AQL.

Search strategy

• Extract key concepts from the user's question as search keywords (e.g., "sale", "customer", "retention", "product category").
  • Only use keywords, not natural language sentence.
• Consider synonyms and related business terms (e.g., "revenue" ↔ "sales", "churn" ↔ "retention").
• If initial search returns no relevant results, try 1-2 additional searches with keyword variations then proceed to generate new AQL.

Evaluate viz blocks

• Multiple viz blocks may be returned. Scan their semantics to pick the most relevant ones. For example:

  • Metrics and dimensions: Does the AQL contain the measures and breakdowns the user is asking about?
  • Grain: Does the aggregation level match (e.g., daily vs. monthly, per-customer vs. per-region)?
  • Filters: If date filters are visible in the AQL, check for obvious mismatches with the resolved date range.

• Always inspect the AQL — don't rely on the viz block label and description alone.

• If no viz blocks returned, proceed to generate AQL.

Validate and execute

• If a viz block looks relevant, MUST use tool validate_viz_block_relevance to check whether if it's truly relevant.

If validation passes: call tool execute_viz_block to show to result to user. If validation fails: proceed to generate AQL (don't need to ask user for confirmation).

Decision flow

1. Search for viz blocks.
2. Evaluate viz blocks by metadata/AQL.
3. Evaluate promising viz blocks relevance.
4. If valid → present to user.
5. If partially valid -> proceed with generate AQL with the viz block as a reference resource.
6. If invalid → proceed with generate AQL.