build_cluster_expression

Description: Converts a freeform natural language audience description into a structured cluster expression and optional geographic filter for use with find_persons. Automates the process of searching for relevant clusters, selecting the best matches, and building a boolean expression.

Tool Identifier: build_cluster_expression

Input Parameters

Parameter	Type	Required	Default	Constraints	Description
audience_context	object	Yes	-	See below	Natural language description of the target audience
max_criteria	number	No	5	1-10	Maximum number of criteria to extract from the description
workflow_id	string	No	-	Valid UUID	Workflow session identifier for tracking

audience_context Object:

Field	Type	Required	Default	Constraints	Description
base_prompt	string	Yes	-	10-1000 chars	Freeform natural language audience description
refinements	array	No	[]	string[]	Optional refinements to adjust criteria

Request Schema:

interface BuildClusterExpressionParams {
  audience_context: {
    base_prompt: string;
    refinements?: string[];
  };
  max_criteria?: number;
  workflow_id?: string;
}

Output Format

Success Response:

{
  expression: string;              // Boolean expression using cluster hashes for find_persons
  geo_filter: {                    // Geographic filter (null if no location mentioned)
    latitude: number;
    longitude: number;
    radius: number;
    unit: "km" | "miles";
  } | null;
  estimated_size: number;          // Estimated audience size
  criteria_mapping: Array<{        // How each criterion was matched
    criterion: string;
    selected_cluster: {
      cluster_hash: string;
      cluster_name: string;
      cluster_value: string;
      domain: string;
      size: number;
      similarity_score: number;
    };
    alternatives: Array<{...}>;    // Other candidate clusters
  }>;
  parsed_input: {                  // What was extracted from the prompt
    criteria: string[];
    geo_description: string | null;
    geo_radius: number | null;
    geo_unit: "km" | "miles" | null;
    desired_size: number;
  };
  expression_reasoning: string;    // LLM explanation of expression construction
  tool_trace_id: string;
  workflow_id: string;
}

Example Response:

{
  "expression": "a8f3bc1d2e3f4a5b AND b2e4df5a6b7c8d9e",
  "geo_filter": {
    "latitude": 37.7749,
    "longitude": -122.4194,
    "radius": 50,
    "unit": "miles"
  },
  "estimated_size": 52000,
  "criteria_mapping": [
    {
      "criterion": "high income over $150,000",
      "selected_cluster": {
        "cluster_hash": "a8f3bc1d2e3f4a5b",
        "cluster_name": "individual_income_range",
        "cluster_value": "150000_plus",
        "domain": "demographic",
        "size": 5000000,
        "similarity_score": 0.92
      },
      "alternatives": [
        {
          "cluster_hash": "c3f5de8a9b0c1d2e",
          "cluster_name": "household_income_range",
          "cluster_value": "150000_plus",
          "domain": "household",
          "size": 4500000,
          "similarity_score": 0.85
        }
      ]
    },
    {
      "criterion": "golf interest or affinity",
      "selected_cluster": {
        "cluster_hash": "b2e4df5a6b7c8d9e",
        "cluster_name": "golf_affinity",
        "cluster_value": "high",
        "domain": "affinity",
        "size": 3000000,
        "similarity_score": 0.95
      },
      "alternatives": []
    }
  ],
  "parsed_input": {
    "criteria": ["high income over $150,000", "golf interest or affinity"],
    "geo_description": "San Francisco, CA",
    "geo_radius": 50,
    "geo_unit": "miles",
    "desired_size": 50000
  },
  "expression_reasoning": "Used AND to combine income and golf criteria for precision targeting in the SF Bay Area.",
  "tool_trace_id": "a1b2c3d4e5f6",
  "workflow_id": "550e8400-e29b-41d4-a716-446655440000"
}

Error Handling

Common Errors:

Empty prompt: "Audience base_prompt cannot be empty"
Prompt too short: "Audience description is too short. Please provide more detail about your target audience."
No matching clusters: "Could not find matching clusters for any of the extracted criteria. Please try a different audience description with more specific characteristics."
Invalid expression: "Expression builder selected cluster hashes not present in search results. Please try again with a different audience description."

Usage Examples

Example 1: Simple audience description

{
  "audience_context": {
    "base_prompt": "High income golf enthusiasts in San Francisco"
  }
}

Example 2: Detailed description with refinements

{
  "audience_context": {
    "base_prompt": "Tech executives making over $200K who are interested in luxury travel and golf",
    "refinements": ["Focus on the Bay Area", "Prefer a larger audience around 200K"]
  },
  "max_criteria": 4
}

Example 3: Nationwide audience, no geo filter

{
  "audience_context": {
    "base_prompt": "Young parents aged 25-40 interested in organic baby products, nationwide, about 500K people"
  }
}

Using the Output with find_persons

The expression and geo_filter fields map directly to find_persons parameters:

{
  "name": "find_persons",
  "arguments": {
    "expression": "<expression from build_cluster_expression>",
    "location": "<geo_filter from build_cluster_expression>",
    "identifier_type": "email",
    "format": "csv"
  }
}

The criteria_mapping output shows which clusters were selected and why, allowing you to review and adjust the expression before passing it to find_persons.