Clarification Policy Files
A clarification policy file tells the agent when to proceed with a default assumption and when to ask a clarifying question. It controls how the agent handles ambiguous or vague user requests.
Frontmatter
---
type: behavior
kind: clarification_policy
domain: "*" # or a specific domain name
---type
behavior
Identifies this as a behavior file
kind
clarification_policy
Marks this as a clarification policy file
domain
"*", "default", "marketing", etc.
Which domain(s) this applies to
Default Behavior
If no clarification policy file is configured, Lynk applies its built-in clarification policy — a sensible default shared across all Lynk customers. Adding a clarification policy file overrides that default for your project. You are not starting from scratch — you are customizing on top of an existing baseline.
What Goes in a Clarification Policy
When to proceed — cases where the agent should make a default assumption and state it, rather than asking. Define a default for time period and granularity so the agent knows what to assume when the user doesn't specify.
When to ask — when the question is ambiguous or too broad to answer directly. This covers both cases: a question where a parameter needs clarifying, and a question so open-ended there's no single right path. In both cases, the agent asks one focused question and suggests up to 3 concrete options grounded in real data.
Response tone — how the agent should sound when asking or stating an assumption.
Custom Domains
A marketing domain clarification policy applies only to marketing-domain queries. Policies not defined in a custom domain fall back to the domain: "*" file.
Decision Framework
Use this to decide whether a given situation calls for a question or a default assumption:
High — question could mean meaningfully different things
High — wrong assumption changes the answer significantly
Ask a focused question, offer up to 3 concrete options
High
Low — any reasonable interpretation gives a similar answer
Proceed with the most common interpretation; state the assumption at the end
Low — intent is clear
High — the stakes matter but the interpretation is obvious
Proceed and state the assumption clearly inline
Low
Low
Proceed silently
What counts as high ambiguity: multiple metrics could answer the question (ARR vs. MRR vs. cash), multiple entities could be relevant, or scope is underspecified ("how are we doing?").
What counts as high stakes: the answer will be used for a business decision, presented to leadership, or the wrong assumption would look like a data error.
Best Practices
Define your time period and granularity defaults. These are the most common sources of ambiguity in data questions. Decide what the agent should assume when neither is specified and write it down.
Reserve questions for genuinely vague questions. Ask only when a question could be interpreted in multiple meaningfully different ways. When asking, always suggest up to 3 concrete options — this helps users choose quickly rather than re-explain.
Match the decision framework to your audience. Technical users (analysts, data engineers) tolerate more defaults and fewer questions. Non-technical users (marketing, executives) benefit from the agent being more explicit about assumptions.
Keep it general. Clarification policy is not the place for entity-specific SQL rules, filter defaults, or metric definitions. Those belong in task instructions and entity knowledge files.
Common Pitfalls
Putting SQL or filter rules here — rules like "always filter to active customers" or "use net_amount for revenue" belong in task instructions, not clarification policy. Clarification policy is about handling ambiguous inputs, not generating SQL.
Putting entity or metric guidance here — rules like "use this entity when..." or "this metric means..." belong in the entity knowledge file, not clarification policy.
Over-specifying when to ask — if everything triggers a clarification question, the agent becomes annoying. Reserve questions for cases where the ambiguity would genuinely lead to meaningfully different answers.
When to Use This File
Create or update a clarification policy when a situation meets one of these conditions:
The agent should apply a default assumption when a question is ambiguous — time period, granularity, scope
You want to define when the agent should ask a clarifying question vs. proceed with an assumption
You want to configure how the agent handles unknown terms or underspecified requests
Examples:
"When no time period is specified, default to the current quarter" → add a time period default
"When no granularity is specified, default to weekly" → add a granularity default
"When the user asks something vague that could go in several directions, ask and offer options" → define when-to-ask behavior with examples
When NOT to Use This File
If you want SQL rules, filters, or field choices for a specific entity → task instructions file
If you want to define what an entity or metric means, or when to use it → entity knowledge file
If you want to define business terms → glossary file
If you want to control how responses are structured (tables, tone, data notes) → output format file
Full Examples
Example 1 — Grove (B2B SaaS)
The most common sources of ambiguity in Grove queries are the revenue metric (ARR vs. MRR vs. cash collected) and vague scope questions ("how are we doing?" could mean revenue, churn, or both). The default time period is current quarter; the default granularity is monthly.
Example 2 — Bly (E-commerce), marketing domain
Marketing results at Bly are highly date-sensitive — a campaign that looked good over 28 days may look very different over 7 days. This policy always asks about time period for channel and campaign questions, and always asks about granularity when the user's question implies trend analysis.
Example 3 — Arcadia (Mobile gaming)
Arcadia metrics are sensitive to two dimensions users rarely specify: the player segment ("our players" could mean DAU, paying players, or whales — and revenue per player differs dramatically) and the retention window (D7 vs. D30 are not interchangeable). This policy always asks about segment for revenue and ARPDAU questions, and always clarifies retention window when "retention" is mentioned without a number.
Last updated