ai_filters

ai_filters.create

Create AI Filter

Effects: write, external_api

Create a new AI filter for semantic intent-based message matching.

AI filters use vector embeddings (via Voyage AI) to detect whether an incoming message matches a specific intent or topic. The filter's description is embedded as a reference vector at creation time. When a message arrives, its embedding is compared against this reference using cosine similarity.

The description field is the most important part — it becomes the reference embedding that all incoming messages are compared against. Write it as a clear statement of what kind of messages should match:

• 'Customer asking about pricing, subscription plans, or billing'
• 'User reporting a bug, crash, or unexpected behavior in the product'
• 'Inbound sales lead expressing interest in purchasing or trialing'

The threshold controls sensitivity: 0.5 is a balanced default, lower values (0.3) cast a wider net, higher values (0.8) require closer matches.

Note: This tool calls the Voyage AI embedding API to generate the reference vector.

Arguments

Argument	Type	Required	Description
description	string	yes	Reference text that defines what messages should match this filter. This text is embedded as a vector and used for cosine similarity comparison against all incoming messages. Be specific and descriptive — the quality of this text directly determines filter accuracy. E.g. 'Customer asking about pricing, subscription costs, or billing issues'. Max 500 chars.
name	string	yes	Filter name — a short, human-readable label (max 100 chars)
threshold	number	no	Cosine similarity threshold for a message to be considered a match. Range 0.1–1.0. Default 0.50. Lower values (e.g. 0.3) are more permissive and catch more messages. Higher values (e.g. 0.8) require closer semantic similarity. (default 0.5; min 0.1; max 1.0)

ai_filters.delete

Delete AI Filter

Effects: delete

Permanently delete an AI filter.

When to use:

• User wants to remove a filter they no longer need

This action cannot be undone. Any triggers that reference this filter by ID will no longer match it — review and update those triggers after deletion.

Arguments

Argument	Type	Required	Description
filter_id	integer	yes	ID of the filter to delete

ai_filters.list

List AI Filters

Effects: read

List all AI filters for the current workspace.

AI filters are semantic intent-based message filters that use embeddings (vector representations) to detect whether an incoming message matches a specific intent or topic. Unlike keyword filters, they understand meaning: 'I need help with my order' and 'my package hasn't arrived' both match a 'shipping support' filter even without shared keywords.

Each filter stores a reference embedding of its description. When a message arrives, its embedding is compared via cosine similarity against the filter's reference vector. If the similarity exceeds the threshold, the filter matches.

When to use:

• Check which semantic filters already exist before creating a new one
• Get filter IDs for use in trigger conditions
• Review thresholds and active status of existing filters

Returns all filters with id, name, description, threshold, and is_active.

Arguments

No arguments.

ai_filters.test

Test AI Filter

Effects: read, external_api

Test a message against an AI filter to check whether it would match.

This tool embeds the provided message using Voyage AI and computes the cosine similarity between the message vector and the filter's stored reference vector. It returns the similarity score, whether the message would match (similarity >= threshold), and the filter's threshold value.

Use this to:

• Verify a filter works as intended before using it in a trigger
• Tune the threshold by testing borderline messages
• Debug why a message did or did not match a filter in production

Returns: {similarity: float, matched: bool, threshold: float}

Note: This tool calls the Voyage AI embedding API to embed the test message.

Arguments

Argument	Type	Required	Description
filter_id	integer	yes	ID of the filter to test against
message	string	yes	The message text to test. This is embedded and compared against the filter's reference vector via cosine similarity.

ai_filters.update

Update AI Filter

Effects: write, external_api

Update an existing AI filter's name, description, threshold, or active state.

When to use:

• User wants to rename a filter
• User wants to refine the filter description to improve match accuracy
• User wants to adjust the similarity threshold (higher = stricter matching)
• User wants to enable or disable a filter without deleting it

Provide only the fields you want to change. At least one field is required.

Note: If the description is changed, this tool calls the Voyage AI embedding API to re-generate the reference vector with the new description text.

Arguments

Argument	Type	Required	Description
description	string	no	New reference description text. If changed, the Voyage AI embedding API is called to re-generate the reference vector. Max 500 chars. Optional.
filter_id	integer	yes	ID of the filter to update
is_active	boolean	no	Enable (true) or disable (false) the filter. OMIT to leave the active flag unchanged.
name	string	no	New filter name (max 100 chars, optional)
threshold	number	no	New cosine similarity threshold. Range 0.1–1.0. Optional. (min 0.1; max 1.0)