Tools Reference

Quick Reference

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 →