Tag Management

Overview

Tags in vCon are key-value pairs that provide simple, flexible metadata for categorization, filtering, and organization. Tags are stored as a special attachment with type: "tags", encoding: "json", and a body containing an array of "key:value" strings.

Storage Format

Tags are stored internally as an attachment in the vCon:

{
  "type": "tags",
  "encoding": "json",
  "body": "[\"department:sales\", \"priority:high\", \"status:open\"]"
}

This format is automatically managed by the tag tools - you don't need to interact with attachments directly.

Available Tools

1. `add_tag` - Add or Update a Single Tag

Add or update a tag on a vCon.

Input:

{
  vcon_uuid: string;      // UUID of the vCon
  key: string;            // Tag key/name
  value: string | number | boolean;  // Tag value
  overwrite?: boolean;    // Whether to overwrite if exists (default: true)
}

Examples:

// Add a string tag
add_tag({
  vcon_uuid: "123e4567-e89b-12d3-a456-426614174000",
  key: "department",
  value: "sales"
})

// Add a number tag
add_tag({
  vcon_uuid: "123e4567-e89b-12d3-a456-426614174000",
  key: "priority",
  value: 5
})

// Add a boolean tag
add_tag({
  vcon_uuid: "123e4567-e89b-12d3-a456-426614174000",
  key: "resolved",
  value: true
})

// Add tag but don't overwrite if it exists
add_tag({
  vcon_uuid: "123e4567-e89b-12d3-a456-426614174000",
  key: "customer_id",
  value: "CUST-12345",
  overwrite: false
})

Response:

{
  "success": true,
  "message": "Tag 'department' set on vCon 123e4567-e89b-12d3-a456-426614174000",
  "key": "department",
  "value": "sales"
}

2. `get_tag` - Get a Single Tag Value

Retrieve the value of a specific tag.

Input:

{
  vcon_uuid: string;      // UUID of the vCon
  key: string;            // Tag key to retrieve
  default_value?: any;    // Value to return if tag doesn't exist
}

Examples:

// Get a tag value
get_tag({
  vcon_uuid: "123e4567-e89b-12d3-a456-426614174000",
  key: "department"
})

// Get tag with default value
get_tag({
  vcon_uuid: "123e4567-e89b-12d3-a456-426614174000",
  key: "priority",
  default_value: "normal"
})

Response:

{
  "success": true,
  "key": "department",
  "value": "sales",
  "exists": true
}

3. `get_all_tags` - Get All Tags

Retrieve all tags from a vCon as a key-value object.

Input:

{
  vcon_uuid: string;      // UUID of the vCon
}

Example:

get_all_tags({
  vcon_uuid: "123e4567-e89b-12d3-a456-426614174000"
})

Response:

{
  "success": true,
  "vcon_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "tags": {
    "department": "sales",
    "priority": "high",
    "status": "open",
    "customer_id": "CUST-12345"
  },
  "count": 4
}

4. `update_tags` - Update Multiple Tags

Update multiple tags at once.

Input:

{
  vcon_uuid: string;      // UUID of the vCon
  tags: {                 // Object with tag key-value pairs
    [key: string]: string | number | boolean;
  };
  merge?: boolean;        // If true, merge with existing tags (default: true)
}

Examples:

// Merge new tags with existing ones
update_tags({
  vcon_uuid: "123e4567-e89b-12d3-a456-426614174000",
  tags: {
    region: "west",
    team: "alpha",
    priority: "high"
  },
  merge: true
})

// Replace all tags
update_tags({
  vcon_uuid: "123e4567-e89b-12d3-a456-426614174000",
  tags: {
    status: "archived",
    archived_at: "2025-10-14"
  },
  merge: false  // This removes all existing tags
})

Response:

{
  "success": true,
  "message": "Tags merged on vCon 123e4567-e89b-12d3-a456-426614174000",
  "tags": {
    "region": "west",
    "team": "alpha",
    "priority": "high"
  }
}

5. `remove_tag` - Remove a Single Tag

Remove a specific tag from a vCon.

Input:

{
  vcon_uuid: string;      // UUID of the vCon
  key: string;            // Tag key to remove
}

Example:

remove_tag({
  vcon_uuid: "123e4567-e89b-12d3-a456-426614174000",
  key: "priority"
})

Response:

{
  "success": true,
  "message": "Tag 'priority' removed from vCon 123e4567-e89b-12d3-a456-426614174000"
}

6. `remove_all_tags` - Remove All Tags

Remove all tags from a vCon.

Input:

{
  vcon_uuid: string;      // UUID of the vCon
}

Example:

remove_all_tags({
  vcon_uuid: "123e4567-e89b-12d3-a456-426614174000"
})

Response:

{
  "success": true,
  "message": "All tags removed from vCon 123e4567-e89b-12d3-a456-426614174000"
}

7. `search_by_tags` - Search vCons by Tags

Search for vCons that have specific tag values. All specified tags must match (AND logic).

Input:

{
  tags: {                 // Tag key-value pairs to search for
    [key: string]: string;
  };
  limit?: number;         // Maximum UUIDs to return (default: 50, max: 100)
  return_full_vcons?: boolean;  // Return full vCon objects (default: auto based on result size)
  max_full_vcons?: number;      // Max full vCon objects to return (default: 20)
}

Behavior:

Always returns vcon_uuids for all matching vCons (up to limit)
For small result sets (≤20), full vCon objects are returned by default
For large result sets (>20), only UUIDs are returned by default to prevent response size limits
Use get_vcon to fetch individual vCons by UUID when needed

Examples:

// Find all sales department vCons (returns UUIDs for large sets)
search_by_tags({
  tags: {
    department: "sales"
  }
})

// Find high-priority open sales calls (small set, returns full vCons)
search_by_tags({
  tags: {
    department: "sales",
    priority: "high",
    status: "open"
  },
  limit: 10
})

// Explicitly request full vCons for large result set (limited to 20)
search_by_tags({
  tags: {
    direction: "out",
    engagement: "true"
  },
  limit: 100,
  return_full_vcons: true,
  max_full_vcons: 20
})

Response:

{
  "success": true,
  "count": 2,
  "tags_searched": {
    "department": "sales",
    "priority": "high"
  },
  "vcon_uuids": [
    "123e4567-e89b-12d3-a456-426614174000",
    "987fcdeb-51a2-43f1-b9c6-d8e7f6a5b4c3"
  ],
  "vcons": [
    { /* full vCon object */ },
    { /* full vCon object */ }
  ]
}

8. `get_unique_tags` - Get All Unique Tags

Get a list of all unique tag keys and their possible values across all vCons. This is useful for:

Discovering what tags are in use
Building tag selection UIs
Analytics and reporting
Understanding your tag taxonomy

Input:

{
  include_counts?: boolean;  // Include usage counts (default: false)
  key_filter?: string;       // Filter by key substring (case-insensitive)
  min_count?: number;        // Minimum occurrence count (default: 1)
}

Examples:

// Get all unique tags
get_unique_tags({})

// Get all unique tags with usage counts
get_unique_tags({
  include_counts: true
})

// Get only department-related tags
get_unique_tags({
  key_filter: "department",
  include_counts: true
})

// Get tags that appear at least 5 times
get_unique_tags({
  include_counts: true,
  min_count: 5
})

Response (without counts):

{
  "success": true,
  "unique_keys": [
    "campaign",
    "department",
    "priority",
    "region",
    "status"
  ],
  "unique_key_count": 5,
  "tags_by_key": {
    "campaign": ["spring_2024", "summer_2024", "fall_2024"],
    "department": ["engineering", "sales", "support"],
    "priority": ["high", "low", "medium"],
    "region": ["east", "north", "south", "west"],
    "status": ["closed", "open", "pending"]
  },
  "total_vcons_with_tags": 150,
  "summary": {
    "total_unique_keys": 5,
    "total_vcons": 150,
    "filter_applied": false,
    "min_count_filter": 1
  }
}

Response (with counts):

{
  "success": true,
  "unique_keys": ["department", "priority", "status"],
  "unique_key_count": 3,
  "tags_by_key": {
    "department": ["engineering", "sales", "support"],
    "priority": ["high", "low", "medium"],
    "status": ["closed", "open"]
  },
  "counts_per_value": {
    "department": {
      "sales": 45,
      "support": 38,
      "engineering": 22
    },
    "priority": {
      "high": 30,
      "medium": 50,
      "low": 25
    },
    "status": {
      "open": 60,
      "closed": 45
    }
  },
  "total_vcons_with_tags": 150,
  "summary": {
    "total_unique_keys": 3,
    "total_vcons": 150,
    "filter_applied": false,
    "min_count_filter": 1
  }
}

Use Cases:

UI Building: Populate dropdown menus with available tag values
Analytics: Understand tag distribution and usage patterns
Data Quality: Find tags that are rarely used or might be misspelled
Tag Cleanup: Identify tags that should be standardized or removed

Integration with Search Tools

Tags can also be used to filter results in the main search tools:

Keyword Search with Tags

search_vcons_content({
  query: "customer complaint",
  tags: {
    department: "support",
    priority: "high"
  }
})

Semantic Search with Tags

search_vcons_semantic({
  query: "billing issues",
  tags: {
    department: "billing",
    status: "open"
  }
})

Hybrid Search with Tags

search_vcons_hybrid({
  query: "refund request",
  tags: {
    department: "sales",
    region: "west"
  }
})

Tag Discovery and Analytics

Get All Tags in Your System

// Discover all tags
const result = get_unique_tags({ include_counts: true })

// Result shows:
// - All tag keys in use
// - All possible values for each key
// - How many vCons have each value
// - Total vCons with tags

Build Tag Selection UI

// Get available department values
const tags = get_unique_tags({
  key_filter: "department"
})

// Use tags.tags_by_key.department to populate dropdown:
// ["sales", "support", "engineering"]

Find Rarely Used Tags

// Get tags that appear at least 10 times
const commonTags = get_unique_tags({
  include_counts: true,
  min_count: 10
})

// Tags not in this result appear < 10 times
// Consider standardizing or removing them

Analyze Tag Distribution

const analysis = get_unique_tags({
  include_counts: true
})

// Analysis shows:
// - Which departments handle the most conversations
// - Priority distribution across your organization
// - Status breakdown

Common Use Cases

1. Customer Tracking

// Tag a vCon with customer information
add_tag({
  vcon_uuid: vcon_uuid,
  key: "customer_id",
  value: "CUST-12345"
})

add_tag({
  vcon_uuid: vcon_uuid,
  key: "customer_name",
  value: "Acme Corp"
})

// Find all conversations with a specific customer
search_by_tags({
  tags: { customer_id: "CUST-12345" }
})

2. Department Organization

// Tag conversations by department
update_tags({
  vcon_uuid: vcon_uuid,
  tags: {
    department: "sales",
    team: "enterprise",
    region: "west"
  }
})

// Find all sales conversations
search_by_tags({
  tags: { department: "sales" }
})

3. Status Tracking

// Set initial status
add_tag({
  vcon_uuid: vcon_uuid,
  key: "status",
  value: "open"
})

// Update when resolved
add_tag({
  vcon_uuid: vcon_uuid,
  key: "status",
  value: "resolved"
})

add_tag({
  vcon_uuid: vcon_uuid,
  key: "resolved_at",
  value: new Date().toISOString()
})

// Find all open issues
search_by_tags({
  tags: { status: "open" }
})

4. Priority Management

// Set priority level
add_tag({
  vcon_uuid: vcon_uuid,
  key: "priority",
  value: "high"
})

// Find high priority items
search_by_tags({
  tags: { priority: "high" }
})

5. Campaign Tracking

// Tag conversations from a campaign
update_tags({
  vcon_uuid: vcon_uuid,
  tags: {
    campaign: "spring_2024",
    source: "web_chat",
    promotion: "free_trial"
  }
})

// Analyze campaign performance
search_by_tags({
  tags: { campaign: "spring_2024" }
})

Best Practices

Tag Naming

Use lowercase with underscores: customer_id, created_date
Be consistent across your application
Avoid spaces in tag keys
Use descriptive names: priority instead of p

Tag Values

Keep values simple and consistent
Use a predefined set of values for categorical tags (e.g., status: "open", "closed", "pending")
For dates, use ISO 8601 format: "2025-10-14T10:30:00Z"
For booleans, use "true" or "false" strings

Performance

Use tags for filtering, not for storing large amounts of data
Limit the number of tags per vCon to what's needed
Tags are indexed for fast searching
Consider using the materialized view for tag-heavy queries

Organization

Define a tagging schema for your application
Document which tags are used and their possible values
Use tags hierarchically: department, then team, then region

Technical Details

Storage

Tags are stored as an attachment with type: "tags"
The attachment has encoding: "json"
The body contains a JSON array of "key:value" strings
Example: ["department:sales", "priority:high"]

Querying

Tags are indexed using a GIN index for fast containment queries
A materialized view (vcon_tags_mv) provides optimized tag queries
Search functions use JSONB containment operators (@>)

Updates

Adding/updating tags modifies the tags attachment
If no tags attachment exists, one is created
The vCon's updated_at timestamp is updated on tag changes
Tags are atomic - you can't have partial updates

Troubleshooting

Tag not appearing after adding

Check that the vCon UUID is correct
Verify the tag was added successfully (check response)
Use get_all_tags to see all current tags

Search returning unexpected results

Remember that search_by_tags uses AND logic (all tags must match)
Check that tag values match exactly (case-sensitive)
Verify tags are strings in the search query

Performance issues

Consider refreshing the materialized view: REFRESH MATERIALIZED VIEW vcon_tags_mv;
Check index usage with EXPLAIN ANALYZE
Limit the number of tags per vCon

Examples in Different Scenarios

Phone Call Center

// Tag incoming calls
update_tags({
  vcon_uuid: call_uuid,
  tags: {
    call_type: "inbound",
    department: "support",
    queue: "technical",
    wait_time_seconds: "45",
    handled_by: "agent_123"
  }
})

Chat Support

// Tag chat sessions
update_tags({
  vcon_uuid: chat_uuid,
  tags: {
    channel: "web_chat",
    topic: "billing",
    sentiment: "negative",
    escalated: "true",
    satisfaction_score: "2"
  }
})

Email Threads

// Tag email conversations
update_tags({
  vcon_uuid: email_uuid,
  tags: {
    thread_id: "THREAD-789",
    category: "inquiry",
    product: "enterprise_plan",
    responded: "true",
    response_time_hours: "2.5"
  }
})

Migration from Other Systems

If you're migrating from systems that use different tag formats:

From flat metadata

// Old: { metadata: { dept: "sales", pri: 5 } }
// New:
update_tags({
  vcon_uuid: vcon_uuid,
  tags: {
    department: "sales",
    priority: "5"
  }
})

From nested structures

// Old: { tags: { category: { primary: "support", secondary: "billing" } } }
// New: Flatten the structure
update_tags({
  vcon_uuid: vcon_uuid,
  tags: {
    category_primary: "support",
    category_secondary: "billing"
  }
})

API Reference

For the complete API reference, see the tool definitions in src/tools/tag-tools.ts.

For database implementation details, see the query methods in src/db/queries.ts.

PreviousSearch & Query NextQuery Prompts

Last updated 2 months ago

Good afternoon

hashtagOverview

hashtagStorage Format

hashtagAvailable Tools

hashtag1. add_tag - Add or Update a Single Tag

hashtag2. get_tag - Get a Single Tag Value

hashtag3. get_all_tags - Get All Tags

hashtag4. update_tags - Update Multiple Tags

hashtag5. remove_tag - Remove a Single Tag

hashtag6. remove_all_tags - Remove All Tags

hashtag7. search_by_tags - Search vCons by Tags

hashtag8. get_unique_tags - Get All Unique Tags

hashtagIntegration with Search Tools

hashtagKeyword Search with Tags

hashtagSemantic Search with Tags

hashtagHybrid Search with Tags

hashtagTag Discovery and Analytics

hashtagGet All Tags in Your System

hashtagBuild Tag Selection UI

hashtagFind Rarely Used Tags

hashtagAnalyze Tag Distribution

hashtagCommon Use Cases

hashtag1. Customer Tracking

hashtag2. Department Organization

hashtag3. Status Tracking

hashtag4. Priority Management

hashtag5. Campaign Tracking

hashtagBest Practices

hashtagTag Naming

hashtagTag Values

hashtagPerformance

hashtagOrganization

hashtagTechnical Details

hashtagStorage

hashtagQuerying

hashtagUpdates

hashtagTroubleshooting

hashtagTag not appearing after adding

hashtagSearch returning unexpected results

hashtagPerformance issues

hashtagExamples in Different Scenarios

hashtagPhone Call Center

hashtagChat Support

hashtagEmail Threads

hashtagMigration from Other Systems

hashtagFrom flat metadata

hashtagFrom nested structures

hashtagAPI Reference

Overview

Storage Format

Available Tools

1. `add_tag` - Add or Update a Single Tag

2. `get_tag` - Get a Single Tag Value

3. `get_all_tags` - Get All Tags

4. `update_tags` - Update Multiple Tags

5. `remove_tag` - Remove a Single Tag

6. `remove_all_tags` - Remove All Tags

7. `search_by_tags` - Search vCons by Tags

8. `get_unique_tags` - Get All Unique Tags

Integration with Search Tools

Keyword Search with Tags

Semantic Search with Tags

Hybrid Search with Tags

Tag Discovery and Analytics

Get All Tags in Your System

Build Tag Selection UI

Find Rarely Used Tags

Analyze Tag Distribution

Common Use Cases

1. Customer Tracking

2. Department Organization

3. Status Tracking

4. Priority Management

5. Campaign Tracking

Best Practices

Tag Naming

Tag Values

Performance

Organization

Technical Details

Storage

Querying

Updates

Troubleshooting

Tag not appearing after adding

Search returning unexpected results

Performance issues

Examples in Different Scenarios

Phone Call Center

Chat Support

Email Threads

Migration from Other Systems

From flat metadata

From nested structures

API Reference