Skip to main content
Use this page when you need to understand what a Capsulate pattern contains and what patterns_update_definition expects.

​
What a pattern is

A pattern is the extraction definition behind a canvas. It tells Capsulate:
  • which messages are relevant
  • which entity type to produce
  • which fields to extract
  • how entities should be consolidated
In MCP, patterns are:
  • created together with a canvas via canvas_create_with_pattern
  • edited later via patterns_update_definition
  • inspected via patterns_list, fetch, search, and records_schema

​
User-managed research fields

External assistants should add fields through canvas_column_preview / canvas_column_apply when those tools are deployed. The saved field is user-managed, so email extraction leaves its value alone. Columns belong to the pattern: inspect all affected Canvases before applying a preview. Use finding contribution tools to attach external evidence and reviewed values; editing data_points alone does not publish findings. See MCP Tools for availability and supported scalar types. Pattern updates validate the caller’s definition. Eligible state values with missing semantic badge tones may use Capsulate’s low-cost model for tone classification.

​
Core fields

A persisted pattern definition includes these main fields:
  • name
  • description
  • entity_type
  • keywords
  • data_points
  • search_filters
  • llm_description
  • distinct_fields
  • automatic_consolidation
  • consolidation_primary_strategy
  • consolidation_hints
  • is_active
confidence_threshold is an entity-query filter, not persisted pattern configuration, so patterns_update_definition does not accept it.

​
Minimal useful pattern

At minimum, a valid pattern needs:
  • at least one keyword
  • an entity_type
  • at least one data_point
Example:

​
data_points

data_points defines the extracted fields for the entity type. Each item is an object with:
  • name required
  • id optional
  • type optional, defaults to text
  • description optional
  • role optional
  • allowedValues optional
  • required optional
Example:

​
Normalization rules

When you update a pattern through patterns_update_definition, Capsulate normalizes the definition before saving it.

​
String cleanup

  • Empty strings are treated as missing.
  • name, description, and llm_description are trimmed.

​
entity_type

entity_type is normalized into a stable field-safe identifier:
  • lowercased
  • non-alphanumeric characters become _
  • leading/trailing _ are removed
Example:

​
keywords

Keywords are:
  • trimmed
  • deduplicated case-insensitively
  • kept in first-seen order
Example:

​
data_points.id

If a data point does not include id, Capsulate derives one from the provided id or name. Example:
IDs must be unique across the pattern. During Canvas creation, data point IDs are still provisional. Renaming a proposed field changes its schema identity, and any calculated fields that depend on the old ID must be removed or reconfigured before creation. After a Canvas has been created, treat data_points.id as an immutable storage and binding key. Changing data_points.name changes only the display name; it does not change what the field means or migrate stored entity values. To track different information, add a new data point ID and retire the old field. Existing entity data remains preserved when a field is retired. A field cannot be removed while a Canvas dashboard widget still binds to it; update the widget specification first.

​
distinct_fields

distinct_fields is normalized to a deduplicated list of field IDs. Example:
Each distinct_field must reference an existing data_points[].id. For best results, define fields as if they were a stable public schema:
  • keep id values short, stable, and machine-friendly
  • make name human-readable
  • add description when the field meaning is not obvious
  • use allowedValues for status-like or category-like fields
  • keep most fields optional unless they are truly mandatory for the record
Example:

​
role

role helps clarify how a field behaves in the record:
  • identity: identifies the real-world item
  • state: expected to change over time
  • descriptive: contextual information
Typical examples:
  • identity: tracking_number, order_id, account_id
  • state: status, delivery_date, renewal_date
  • descriptive: merchant, category, amount
Use identity sparingly. Most fields are descriptive.

​
Consolidation fields

These fields control how Capsulate groups or deduplicates entities:
  • distinct_fields
  • automatic_consolidation
  • consolidation_primary_strategy
  • consolidation_hints
Important rule:
  • if distinct_fields is empty and automatic_consolidation is still enabled, the update may still succeed with a warning

​
search_filters

search_filters narrows which messages are considered for the pattern. Common fields include:
  • exclude_sent
  • exclude_spam
  • exclude_promotional
  • exclude_archived
  • has_attachments
  • sender_patterns
  • exclude_domains
  • from_email
  • domain
  • subject
  • categories
  • date_from
  • date_to
Use only the filters that clearly improve precision for the pattern.

​
llm_description

llm_description is the pattern’s natural-language relevance guide. Good descriptions are explicit about:
  • what should be included
  • what should be excluded
  • the difference between real target emails and nearby noise
Good example:

​
Validation behavior

patterns_update_definition returns one of two outcomes:

​
Valid update

  • the normalized pattern is persisted
  • response includes:
    • pattern
    • validation
    • normalized_pattern

​
Invalid update

  • nothing is persisted
  • response includes:
    • errors
    • warnings
    • summary
    • normalized_pattern
That means MCP clients can inspect the normalized output even on validation failure.

​
Common validation failures

Typical failures include:
  • name is empty
  • entity_type is empty
  • keywords is empty after trimming
  • data_points is not an array
  • data_points[].name is missing
  • duplicate data point IDs
  • distinct_fields references a field that does not exist
  • distinct_fields points at a display name instead of a field ID after normalization

​
Example deterministic update

Normalized result:

​
MCP guidance

Use this pattern workflow:
  1. patterns_list or search(type="pattern")
  2. fetch(pattern:...)
  3. records_schema to inspect observed field coverage
  4. patterns_update_definition with deterministic edits
  5. patterns_status to inspect extraction status afterward
If you are creating a new pattern for end users, use canvas_create_with_pattern rather than trying to treat pattern creation as a standalone user flow.