Skip to main content
The quality of your behavior detection is directly tied to the quality of your detailed_description. Velma reads your description as instructions — the more precisely you define the signal, the more reliably it identifies it.

​
Start with the title and short description

Before writing your detailed_description, nail the name and short_description first. These aren’t labels — they set the frame for everything that follows.
  • name — keep it under five words. It should be specific enough that someone unfamiliar with your setup understands immediately what the behavior catches. “Aggressive Language” is okay. “Customer Threat Toward Agent” is better.
  • short_description — one sentence, the dictionary definition of the behavior. If you can’t summarize it in one sentence, the behavior is probably trying to do too much. Consider splitting it.
Once these are locked, use them as the definition to check your criteria against as you write the detailed_description.

​
Write criteria, not examples

Your detailed_description should be a list of explicit conditions that must be met for the behavior to fire. This is not a list of examples. Examples narrow down what the system looks for and produce unreliable results when the audio doesn’t match them closely. Criteria define the underlying structure the examples would satisfy. Do this:
Not this:

​
Ground criteria in concrete language

Vague terms like “insults,” “hateful language,” or “inappropriate content” require Velma to make its own interpretive judgment — and that judgment may not match what you intended. Ground your criteria in concrete linguistic elements: sentence structure, subject-verb relationships, tense, person, and specific word types. Vague:
Concrete:
The more you can translate the behavior into something closer to a grammar or structure check rather than a social context judgment, the more consistent your results will be.

​
Don’t restate the title in the description

If your behavior is named “Coercion Manipulation” and your description says “identify patterns of harassment and intimidation,” you haven’t told Velma anything it didn’t already infer from the title. The detailed_description must go deeper — into specific structural and linguistic markers — not sideways into synonyms. Whenever you find yourself using words that mean the same thing as the behavior name, that is a signal the criteria need more work.

​
Specify who can trigger a behavior

Many behaviors are only meaningful when a specific participant exhibits them. A question like “Can you confirm the account number?” is routine from an agent, but a potential fraud signal from a customer. Without scoping, you will generate false positives. Use applies_to_participant_role_uuids to restrict detection to specific roles:
If role-based scoping alone isn’t sufficient, you can also encode the role context directly in the detailed_description:

​
Include negation criteria

Once you have defined what the behavior catches, spend equal time on what it should not catch. Negation criteria prevent false positives from content that superficially resembles the target signal but isn’t what you’re after. A useful technique: think of the most common thing that looks like the behavior but clearly isn’t, then write a rule that excludes it.

​
Define your umbrella terms

Broad category terms like “personal information,” “sensitive topics,” or “inappropriate content” will be interpreted by Velma using its own judgment. That judgment may not match what you have in mind for your specific industry or context. Always follow a broad term with an explicit list of what it includes. Without definition:
With definition:

​
Scope to context, not universality

A behavior that works well in one context rarely translates cleanly to another. A “return fraud” behavior scoped to an online clothing retailer will have different signals than return fraud at a food delivery service. Trying to write a single behavior that handles every edge case produces a definition that is harder to tune and less precise. Write a tighter version for the context you are actually working in. You can always create multiple variants for different conversation types using applies_to_conversation_type_uuids.

​
Checklist before you ship

1

Title and short description are locked

Name is under five words and unambiguous. Short description summarizes the behavior in one sentence.
2

Criteria are explicit conditions, not examples

The detailed description is a list of testable rules, not illustrative cases.
3

Criteria are grounded in language structure

Terms like “subject,” “adjective,” “future tense,” “conditional framing” rather than “insults,” “hostility,” “inappropriate content.”
4

Negation criteria are present

At least one “do not flag if” rule covering the most common false positive case.
5

Role scope is set if relevant

Behaviors that only apply to one participant type are scoped via applies_to_participant_role_uuids or have role context in the description.
6

Umbrella terms are defined

Any broad category term is followed by a concrete list of what it means in this context.
7

Configuration is stored externally

Velma does not persist behavior definitions between sessions. Your BatchConfig — including all UUIDs and description text — is stored in your own system so you can reproduce it reliably.

​
What to avoid

If your detailed_description contains the words “any,” “all,” or “every” without a bounded list, that is a signal the scope is too broad. These words tend to expand coverage in ways that are hard to predict and produce inconsistent results.