Skip to main content

​
Quick Reference

ToolCategoryPurpose
contextualizeInitial ContextBootstrap analysis with company and data overview
get_account_infoCompany InformationRetrieve company metadata and glossary
data_collection_strategyStrategy PlanningPlan complex multi-step analyses
create_a_threadSession ManagementStart new analysis session
ask_a_questionData AnalysisContinue analysis within existing session
ask_a_single_questionData AnalysisQuick standalone questions
ask_questionsData AnalysisSubmit multiple questions in parallel
wait_for_completionQuery MonitoringMonitor progress of multiple queries
check_question_statusQuery MonitoringCheck status of individual inquiry
get_questions_dataQuery ResultsRetrieve results from multiple queries
get_thread_dataSession ManagementGet complete session data
get_recent_threadsSession ManagementList recent analysis sessions
get_semantic_layer_summaryData DiscoveryOverview of all data entities
get_semantic_layer_entityData DiscoveryDetailed entity information
search_semantic_layerData DiscoverySearch entities by keyword
run_sql_queryAdvancedExecute direct SQL queries
logoutAuthenticationClear authentication credentials

​
Initial Context

​
contextualize

Bootstrap your analysis session with company info and available data entities in one call. Purpose: Provides initial context about your organization’s data and available capabilities. Parameters: None Example Request: 
{
  "name": "contextualize",
  "arguments": {}
}
Example Response: 
{
  "company_info": {
    "name": "Example Corp",
    "industry": "SaaS",
    "business_model": "Subscription"
  },
  "available_entities": [
    "Revenue",
    "Subscriptions", 
    "Customers",
    "Churn"
  ],
  "capabilities": "Analysis tools available..."
}
When to Use:
  • Start of every analysis session
  • When exploring what data is available
  • Before planning complex analyses

​
Company Information

​
get_account_info

Retrieve company metadata, business model, and glossary. Purpose: Get detailed information about your organization’s business context and data definitions. Parameters: None Example Request: 
{
  "name": "get_account_info",
  "arguments": {}
}
Example Response: 
{
  "company": {
    "name": "Example Corp",
    "industry": "Technology",
    "business_model": "B2B SaaS"
  },
  "glossary": {
    "MRR": "Monthly Recurring Revenue",
    "CAC": "Customer Acquisition Cost",
    "LTV": "Customer Lifetime Value"
  }
}
When to Use:
  • Understanding business context
  • Getting definitions for business terms
  • Setting up automated reporting

​
Strategy and Planning

​
data_collection_strategy

Create a comprehensive data analysis plan before executing queries. Purpose: Plan complex multi-step analyses with strategy documentation. Parameters:
  • strategy (string, required): Detailed analysis plan and approach
Example Request: 
{
  "name": "data_collection_strategy",
  "arguments": {
    "strategy": "Investigate Q1 revenue decline by analyzing: 1) Revenue trends by segment 2) Customer churn patterns 3) New customer acquisition 4) Product performance metrics"
  }
}
Example Response: 
{
  "strategy_recorded": true,
  "next_steps": [
    "Execute parallel queries for each analysis area",
    "Use ask_questions for efficient data collection",
    "Synthesize findings for recommendations"
  ]
}
When to Use:
  • Before complex investigations
  • Multi-phase analysis projects
  • When planning needs documentation

​
Session Management

​
create_a_thread

Start a new conversation session for queries. Purpose: Create isolated session for related queries and analysis. Parameters: None Example Request: 
{
  "name": "create_a_thread",
  "arguments": {}
}
Example Response: 
{
  "session_id": "session_abc123",
  "status": "active",
  "created_at": "2024-03-15T10:30:00Z"
}
When to Use:
  • Starting complex multi-step analysis
  • When you need to track conversation history
  • For organizing related queries

​
get_thread_data

Retrieve all data from a session/thread. Purpose: Get complete conversation history and results from a session. Parameters:
  • session_id (string, required): Session identifier
Example Request: 
{
  "name": "get_thread_data",
  "arguments": {
    "session_id": "session_abc123"
  }
}
When to Use:
  • Reviewing complete analysis
  • Exporting session results
  • Continuing previous analysis

​
get_recent_threads

List recent conversation sessions. Purpose: Retrieve list of your recent analysis sessions. Parameters:
  • limit (integer, optional): Number of sessions to return (default: 5)
Example Request: 
{
  "name": "get_recent_threads",
  "arguments": {
    "limit": 10
  }
}
When to Use:
  • Finding previous analysis
  • Session management
  • Continuing past work

​
Data Analysis

​
ask_a_question

Submit a question to an existing thread. Purpose: Continue analysis within an existing session context. Parameters:
  • session_id (string, required): Session identifier
  • question (string, required): Business question to analyze
  • dimensions (object, optional): Filtering dimensions
Example Request: 
{
  "name": "ask_a_question",
  "arguments": {
    "session_id": "session_abc123",
    "question": "What is the MRR trend over the last 6 months?",
    "dimensions": {
      "region": "North America"
    }
  }
}
Example Response: 
{
  "inquiry_id": "inq_xyz789",
  "status": "processing",
  "estimated_completion": "2024-03-15T10:35:00Z"
}
When to Use:
  • Follow-up questions in analysis
  • Building on previous context
  • Detailed exploration of specific topics

​
ask_a_single_question

Quick question that auto-creates a thread. Purpose: Standalone questions with automatic session management. Parameters:
  • question (string, required): Business question to analyze
  • dimensions (object, optional): Filtering dimensions
Example Request: 
{
  "name": "ask_a_single_question",
  "arguments": {
    "question": "What is our current annual recurring revenue?",
    "dimensions": {}
  }
}
When to Use:
  • Quick metric checks
  • One-off questions
  • Simple data lookups

​
ask_questions

Submit multiple questions in parallel (each gets its own session). Purpose: Efficient parallel processing of multiple independent questions. Parameters:
  • questions (array, required): Array of question objects
    • question (string, required): Business question
    • dimensions (object, optional): Filtering dimensions
Example Request: 
{
  "name": "ask_questions",
  "arguments": {
    "questions": [
      {
        "question": "What is our current MRR?",
        "dimensions": {}
      },
      {
        "question": "What is our churn rate this quarter?",
        "dimensions": {}
      },
      {
        "question": "How many new customers did we acquire last month?",
        "dimensions": {}
      }
    ]
  }
}
Example Response: 
{
  "inquiries": [
    {
      "inquiry_id": "inq_001",
      "question": "What is our current MRR?",
      "status": "processing"
    },
    {
      "inquiry_id": "inq_002", 
      "question": "What is our churn rate this quarter?",
      "status": "processing"
    }
  ],
  "total_inquiries": 3
}
When to Use:
  • Complex analysis requiring multiple data points
  • Building comprehensive reports
  • Parallel data collection for efficiency

​
Query Monitoring

​
wait_for_completion

Wait for multiple inquiries to complete. Purpose: Monitor progress and retrieve results from multiple parallel queries. Parameters:
  • inquiry_ids (array, required): Array of inquiry identifiers
  • return_partial_results (boolean, optional): Return results even if some queries fail
Example Request: 
{
  "name": "wait_for_completion",
  "arguments": {
    "inquiry_ids": ["inq_001", "inq_002", "inq_003"],
    "return_partial_results": true
  }
}
When to Use:
  • After using ask_questions
  • When monitoring multiple parallel queries
  • For comprehensive result collection

​
check_question_status

Check the status of a single inquiry. Purpose: Monitor progress of individual queries. Parameters:
  • inquiry_id (string, required): Inquiry identifier
Example Request: 
{
  "name": "check_question_status",
  "arguments": {
    "inquiry_id": "inq_abc123"
  }
}
Example Response: 
{
  "inquiry_id": "inq_abc123",
  "status": "done",
  "progress": 100,
  "completion_time": "2024-03-15T10:35:00Z"
}
When to Use:
  • Checking individual query progress
  • Debugging slow queries
  • Status monitoring

​
get_questions_data

Get complete data for multiple inquiries. Purpose: Retrieve detailed results and data from multiple completed queries. Parameters:
  • inquiry_ids (array, required): Array of inquiry identifiers
Example Request: 
{
  "name": "get_questions_data",
  "arguments": {
    "inquiry_ids": ["inq_001", "inq_002"]
  }
}
When to Use:
  • Retrieving results from parallel queries
  • Getting detailed data and analysis
  • Export and reporting

​
Data Discovery

​
get_semantic_layer_summary

Get an overview of all available data entities. Purpose: Discover what business data and metrics are available for analysis. Parameters: None Example Request: 
{
  "name": "get_semantic_layer_summary",
  "arguments": {}
}
Example Response: 
{
  "entities": [
    {
      "name": "Revenue",
      "type": "metric",
      "description": "Monthly and annual revenue metrics"
    },
    {
      "name": "Subscriptions",
      "type": "entity", 
      "description": "Subscription lifecycle and metrics"
    }
  ],
  "total_entities": 25
}
When to Use:
  • Exploring available data
  • Planning analysis approach
  • Understanding data capabilities

​
get_semantic_layer_entity

Get detailed information about a specific entity. Purpose: Deep dive into specific data entity capabilities and structure. Parameters:
  • entity_id (string, required): Entity identifier
  • node_id (string, optional): Specific node identifier (alternative to entity_id)
Example Request: 
{
  "name": "get_semantic_layer_entity",
  "arguments": {
    "entity_id": "revenue_entity"
  }
}
Example Response: 
{
  "entity": {
    "name": "Revenue",
    "attributes": [
      "total_revenue",
      "recurring_revenue", 
      "one_time_revenue"
    ],
    "dimensions": [
      "time_period",
      "product_line",
      "region"
    ],
    "relationships": ["connects_to_customers", "connects_to_subscriptions"]
  }
}
When to Use:
  • Understanding specific entity capabilities
  • Planning detailed queries
  • Exploring data relationships

​
search_semantic_layer

Search for entities by keyword. Purpose: Find relevant data entities using keywords and search terms. Parameters:
  • query (string, required): Search term or keyword
Example Request: 
{
  "name": "search_semantic_layer",
  "arguments": {
    "query": "revenue"
  }
}
Example Response: 
{
  "search_term": "revenue",
  "matching_entities": [
    {
      "name": "Monthly Recurring Revenue",
      "entity_id": "mrr_entity",
      "relevance_score": 0.95
    },
    {
      "name": "Total Revenue",
      "entity_id": "total_revenue_entity", 
      "relevance_score": 0.89
    }
  ],
  "total_matches": 5
}
When to Use:
  • Finding relevant data entities
  • Discovering related metrics
  • Keyword-based exploration

​
Advanced Features

​
run_sql_query

Execute direct SQL queries (advanced users). Purpose: Direct SQL execution for advanced users with SQL knowledge. Parameters:
  • query (string, required): SQL query to execute
  • timeout (integer, optional): Query timeout in seconds (default: 30)
  • max_results (integer, optional): Maximum number of results (default: 1000)
Example Request: 
{
  "name": "run_sql_query",
  "arguments": {
    "query": "SELECT DATE_TRUNC('month', created_date) as month, COUNT(*) as new_customers FROM customers WHERE created_date >= '2024-01-01' GROUP BY month ORDER BY month",
    "timeout": 60,
    "max_results": 500
  }
}
When to Use:
  • Custom complex queries
  • Advanced data exploration
  • When semantic layer doesn’t cover specific needs
⚠️ Advanced Feature: Requires SQL knowledge and understanding of your data warehouse schema.

​
Authentication

​
logout

Clear authentication and trigger re-authentication. Purpose: Clear stored authentication credentials and force re-authentication. Parameters: None Example Request: 
{
  "name": "logout",
  "arguments": {}
}
Example Response: 
{
  "status": "success",
  "message": "You have been logged out successfully. Your next request will require authentication."
}
When to Use:
  • Switching user accounts
  • Security cleanup
  • Troubleshooting authentication issues

​
Tool Usage Patterns

​
Simple Analysis Pattern

1. contextualize
2. ask_a_single_question

​
Complex Analysis Pattern

1. contextualize
2. data_collection_strategy
3. ask_questions (parallel)
4. wait_for_completion
5. get_questions_data

​
Data Discovery Pattern

1. get_semantic_layer_summary
2. search_semantic_layer
3. get_semantic_layer_entity

​
Best Practices

​
Performance

  • Use ask_questions for parallel processing
  • Implement proper timeout handling
  • Monitor query progress with status checks

​
Data Quality

  • Always start with contextualize
  • Verify entity availability before complex queries
  • Use appropriate dimensions for filtering

​
Security

  • Use logout for proper session cleanup
  • Don’t store sensitive query results
  • Follow your organization’s data access policies
Next Steps: See common use cases → | API integration examples → | Troubleshooting →