MCP Server Tools

Complete reference for all available MCP server tools.

Overview

The Hello Battle Card MCP server provides 14 tools that allow AI agents to interact with your competitive intelligence data. All tools require API key authentication and work with your workspace data.

Available Tools

get_competitor

Get detailed information about a specific competitor.

Parameters:

competitorId (string, required): The ID of the competitor to retrieve

Returns:

Competitor object with:
- Basic information (name, website, status)
- Company profile
- Products and offerings
- Categories and tags
- Last refresh timestamp

Example:

{
  "name": "get_competitor",
  "arguments": {
    "competitorId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Use Cases:

Getting competitor details for analysis
Checking competitor status
Retrieving company profile information
Accessing competitor metadata

list_competitors

List all competitors for your workspace, optionally filtered by product.

Parameters:

productId (string, optional): Filter competitors by product ID

Returns:

Array of competitor objects
Each competitor includes basic information and status

Example:

{
  "name": "list_competitors",
  "arguments": {
    "productId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Without filter:

{
  "name": "list_competitors",
  "arguments": {}
}

Use Cases:

Getting all competitors in workspace
Finding competitors for a specific product
Listing competitors for analysis
Checking competitor count

get_battlecard

Get a battlecard for a specific competitor and product combination.

Parameters:

competitorId (string, required): The ID of the competitor
productId (string, required): The ID of your product

Returns:

Battlecard object with:
- Why We Win section
- Why We Lose section
- Objections and responses
- Talking points
- Evidence IDs

Example:

{
  "name": "get_battlecard",
  "arguments": {
    "competitorId": "550e8400-e29b-41d4-a716-446655440000",
    "productId": "660e8400-e29b-41d4-a716-446655440001"
  }
}

Use Cases:

Getting battlecard content for sales
Retrieving talking points
Accessing objection handling
Reviewing competitive positioning

get_matrix

Get competitive matrix data (basic cells). The current implementation returns matrix cells; for full matrix (categories, competitors, cell map, our product capabilities) use the REST Matrix API (/api/matrix).

Parameters:

productId (string, optional): Filter by product ID
competitorIds (array of strings, optional): List of competitor IDs to include
includeOurProduct (boolean, optional): Include your product column (requires productId)

Returns:

cells: Array of capability assessment cells. Each cell includes:
- categoryId
- competitorId
- summary (capability points)
- capabilityStatus (SUPERIOR, MATCH, INFERIOR, UNKNOWN)
- evidenceIds (when available)

Example:

{
  "name": "get_matrix",
  "arguments": {
    "productId": "550e8400-e29b-41d4-a716-446655440000",
    "competitorIds": ["comp1", "comp2"],
    "includeOurProduct": true
  }
}

Use Cases:

Getting capability assessments for selected competitors
Identifying strengths/weaknesses per category
Feeding matrix data into AI analysis
Combining with REST matrix API for full metadata

get_intel

Get intel items (evidence and internal notes) for your workspace.

Parameters:

competitorId (string, optional): Filter intel items by competitor ID
ids (array of strings, optional): Specific intel item IDs to retrieve

Returns:

Array of intel item objects with:
- Content
- Type (EVIDENCE or INTERNAL_NOTE)
- Metadata (source type, URL, title, credibility score)
- Timestamps

Example - By competitor:

{
  "name": "get_intel",
  "arguments": {
    "competitorId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Example - By IDs:

{
  "name": "get_intel",
  "arguments": {
    "ids": ["id1", "id2", "id3"]
  }
}

Use Cases:

Retrieving evidence for claims
Accessing collected intelligence
Getting internal notes
Reviewing competitor data sources

trigger_refresh

Trigger a refresh job for a competitor to collect updated intelligence.

Parameters:

competitorId (string, required): The ID of the competitor to refresh

Returns:

Job object with:
- Job ID
- Status
- Progress information

Example:

{
  "name": "trigger_refresh",
  "arguments": {
    "competitorId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Use Cases:

Updating competitor data
Refreshing stale intelligence
Collecting latest information
Triggering re-analysis

Note: Refresh jobs run asynchronously. Use the job ID to track progress.

generate_battlecard

Generate a new battlecard for a competitor and product combination.

Parameters:

competitorId (string, required): The ID of the competitor
productId (string, required): The ID of your product

Returns:

Job object with:
- Job ID
- Status
- Battlecard ID (when complete)

Example:

{
  "name": "generate_battlecard",
  "arguments": {
    "competitorId": "550e8400-e29b-41d4-a716-446655440000",
    "productId": "660e8400-e29b-41d4-a716-446655440001"
  }
}

Use Cases:

Creating new battlecards
Regenerating updated battlecards
Generating battlecards for new products
Refreshing battlecard content

Note: Battlecard generation runs asynchronously. Use the job ID to track progress.

search_intel

Perform semantic search across intel items to find relevant information.

Parameters:

query (string, required): The search query
competitorId (string, optional): Limit search to specific competitor
limit (number, optional): Maximum number of results (default: 10)

Returns:

Array of intel items matching the query, ordered by relevance
Each item includes relevance score

Example:

{
  "name": "search_intel",
  "arguments": {
    "query": "pricing strategy",
    "competitorId": "550e8400-e29b-41d4-a716-446655440000",
    "limit": 5
  }
}

Use Cases:

Finding relevant intelligence
Searching for specific topics
Discovering related information
Exploring competitive data

list_solutions

List all solutions for your workspace. Solutions are high-level themes that group product categories into strategic differentiators.

Parameters: None

Returns:

Array of solution objects with:
- Solution name and description
- Product IDs that contribute
- Category mappings with weights
- AI-generated flag

Example:

{
  "name": "list_solutions",
  "arguments": {}
}

Use Cases:

Getting all solution themes
Understanding solution structure
Reviewing category mappings
Checking solution configuration

get_solution

Get detailed information about a specific solution.

Parameters:

solutionId (string, required): The ID of the solution to retrieve

Returns:

Solution object with:
- Name and description
- Product IDs
- Category mappings with weights
- Creation and update timestamps

Example:

{
  "name": "get_solution",
  "arguments": {
    "solutionId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Use Cases:

Getting solution details
Reviewing category mappings
Understanding solution structure
Checking solution configuration

create_solution

Create a new solution theme.

Parameters:

name (string, required): Solution name (e.g., "Enterprise Security")
description (string, optional): Brief description
productIds (array of strings, required): Product IDs that contribute to this solution
categoryMappings (array, required): Category mappings with weights
- categoryId (string, required): Category ID from the product
- productId (string, required): Product ID this category belongs to
- weight (number, required): Weight between 0.0 and 1.0

Returns:

Created solution object

Example:

{
  "name": "create_solution",
  "arguments": {
    "name": "Enterprise Security",
    "description": "Comprehensive security capabilities",
    "productIds": ["product-id-1"],
    "categoryMappings": [
      {
        "categoryId": "security",
        "productId": "product-id-1",
        "weight": 0.5
      }
    ]
  }
}

Use Cases:

Creating custom solution themes
Grouping categories strategically
Setting up solution matrices
Organizing competitive comparisons

update_solution

Update an existing solution.

Parameters:

solutionId (string, required): The ID of the solution to update
name (string, optional): Updated solution name
description (string, optional): Updated description
productIds (array of strings, optional): Updated product IDs
categoryMappings (array, optional): Updated category mappings

Returns:

Updated solution object

Example:

{
  "name": "update_solution",
  "arguments": {
    "solutionId": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Updated Solution Name",
    "categoryMappings": [
      {
        "categoryId": "security",
        "productId": "product-id-1",
        "weight": 0.6
      }
    ]
  }
}

Use Cases:

Updating solution names
Adjusting category weights
Adding/removing category mappings
Modifying solution configuration

get_solution_matrix

Get solution matrix data for high-level strategic comparison.

Parameters:

competitorIds (array of strings, optional): List of competitor IDs to include
solutionIds (array of strings, optional): List of solution IDs to filter by

Returns:

solutions: Array of solution objects
cells: Array of solution matrix cells with aggregated scores
Each cell includes:
- solutionId and competitorId
- aggregatedScore (0-4, Harvey Ball level)
- contributingCategoryIds (for drill-down)
- evidenceIds

Example:

{
  "name": "get_solution_matrix",
  "arguments": {
    "competitorIds": ["comp1", "comp2"],
    "solutionIds": ["solution1"]
  }
}

Use Cases:

Getting high-level competitive comparison
Accessing solution-level scores
Strategic competitive analysis
Executive-level comparisons

generate_solutions

Trigger AI solution generation from product categories. This analyzes all products and their categories to suggest solution themes.

Parameters: None

Returns:

Message indicating generation status
Note: Full implementation may require web UI or API endpoint

Example:

{
  "name": "generate_solutions",
  "arguments": {}
}

Use Cases:

Auto-generating solution themes
Discovering solution opportunities
Setting up initial solutions
Getting AI suggestions

Note: Full AI solution generation may require additional setup or use of the web UI.

Tool Response Format

All tools return JSON-RPC 2.0 responses:

Success Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    // Tool-specific result data
  }
}

Error Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": {
      "details": "competitorId is required"
    }
  }
}

Error Codes

-32600: Invalid Request
-32601: Method Not Found
-32602: Invalid Params
-32603: Internal Error
-32000: Server Error (custom)
401: Unauthorized (invalid API key)
403: Forbidden (plan restrictions)
404: Not Found (resource doesn't exist)

Authentication

All tool calls require API key authentication:

Header:

X-API-Key: hbc_live_your-api-key-here

Requirements:

Enterprise plan account
Valid API key
API key must not be revoked or expired

Rate Limits

Tool calls are subject to rate limits:

Default: 1000 requests per hour per API key
Rate limit headers included in responses
Exceeding limits returns 429 status

Best Practices

Tool Selection

Use get_competitor for basic competitor info
Use get_battlecard for sales-ready content
Use get_matrix for comparisons
Use search_intel for discovery
Use trigger_refresh to update data
Use generate_battlecard to create content

Error Handling

Always check for errors in responses
Handle rate limit errors gracefully
Verify required parameters are provided
Check resource existence before operations

Performance

Use list_competitors with productId filter when possible
Limit search_intel results appropriately
Cache competitor data when appropriate
Batch operations when possible

Next Steps

MCP Examples - See practical usage examples
MCP Installation - Set up MCP server connection
API Reference - Related REST API endpoints

Overview​

Available Tools​

get_competitor​

list_competitors​

get_battlecard​

get_matrix​

get_intel​

trigger_refresh​

generate_battlecard​

search_intel​

list_solutions​

get_solution​

create_solution​

update_solution​

get_solution_matrix​

generate_solutions​

Tool Response Format​

Error Codes​

Authentication​

Rate Limits​

Best Practices​

Tool Selection​

Error Handling​

Performance​

Next Steps​

Overview

Available Tools

get_competitor

list_competitors

get_battlecard

get_matrix

get_intel

trigger_refresh

generate_battlecard

search_intel

list_solutions

get_solution

create_solution

update_solution

get_solution_matrix

generate_solutions

Tool Response Format

Error Codes

Authentication

Rate Limits

Best Practices

Tool Selection

Error Handling

Performance

Next Steps