Skip to main content
Build answer quality around a clear agent scope, well-defined data, and a repeatable review process. Use the narrowest appropriate place for each business rule so changes stay consistent across your agents.

​
Think specialized, not general

Give each agent one audience and a clear job before tuning its answers. For example, separate sales-pipeline analysis from finance reporting when the teams need different definitions, data access, or output. Use data access controls to enforce the scope. Specialized agents also work best with the AI Router enabled: the more distinct each agent’s focus, description, and data access, the more reliably the router can send each question to the right one — so users don’t have to know which agent to ask. Write an agent description that names its domain, the questions it should receive, and the nearest questions it should not receive. The description helps the router choose an agent; the selected agent’s instructions guide how it answers.

​
Choose where guidance belongs

Use the narrowest durable scope for each piece of information. This keeps one source of truth and gives the agent the context when it needs it, without adding everything to every prompt. Start with the semantic layer. Give metrics, dimensions, and parameters clear names, labels, descriptions, and options. If a colleague could not understand the metadata, an agent is unlikely to interpret it reliably either.

​
Understand names and descriptions in YAML

The meaning of name and description depends on what the YAML defines:

​
See the layers in one example

Suppose a Finance agent needs to investigate an unexpected drop in net revenue:
  • The metric description defines how net revenue is calculated, including its filters and exclusions.
  • An ai_hint tells the agent that users saying “sales” mean this metric, rather than gross revenue.
  • Project context defines a company-specific term such as “board revenue” for every agent in the project.
  • The agent description routes Finance reporting questions to this agent and excludes sales-pipeline questions.
  • The agent instructions set defaults such as fiscal periods, comparison windows, and communication style.
  • A revenue-recognition knowledge document provides the longer accounting policy when the question requires it.
  • An investigate-kpi-change skill defines the repeatable steps, checks, and expected output for this investigation.

​
Avoid conflicts and duplication

Keep each stable fact in one canonical place and link to it instead of copying it into instructions or documents. For example, define what a metric means in its semantic description; let the agent instructions define how answers should be presented. The only documented precedence rule between these inputs is that an ai_hint takes precedence over the semantic description in agent prompts. Do not rely on an assumed hierarchy between instructions, knowledge documents, skills, and project context. Remove contradictions, use the narrowest appropriate scope, and test representative questions after changing any layer.

​
Curating verified answers

Verified answers give your agent checked examples to reference. Curate them around the questions your team needs to answer:
  • Verify diverse examples - Mark answers covering different types of questions and use cases to give your agent a broad knowledge base
  • Quality over quantity - Focus on verifying only your best, most accurate responses. A few excellent examples are better than many mediocre ones
  • Update regularly - As your data and business needs evolve, review your verified answers and update them to reflect current best practices

​
Making evaluations part of your workflow

Treat evaluations as an ongoing loop, not a one-off. Encourage your team to use thumbs-up and thumbs-down as they work, build evaluation suites from the real threads that went wrong, and run them before you ship changes to instructions or your semantic layer to catch regressions before your team encounters them.

​
Writing effective instructions

Think of instructions as the agent’s always-on operating defaults, not its knowledge base. Use them to define how this agent should approach and communicate every answer. Focus on four key areas: the agent’s role and scope, your team’s goals and constraints, how you want data analyzed, and how results should be communicated.

​
What to include

  • Role and scope including the questions the agent should answer and when it should redirect someone elsewhere
  • Communication style for how results should be presented to your team (e.g., “Keep explanations simple for non-technical stakeholders” or “Always include actionable next steps”)
  • Business constraints like regulatory requirements or budget limitations that affect every analysis this agent performs
  • Analysis preferences your team relies on (e.g., “Always compare month-over-month growth” or “Flag any churn rates above 5% as concerning”)
Put shared terminology in project context, stable metric definitions in the semantic layer, longer supporting material in a knowledge document, and task-specific procedures in a custom skill. Good example - Sales Team Agent:
You analyze sales performance for our SaaS company. Focus on MRR, churn, and pipeline health. When MRR growth drops below 10% month-over-month, flag it as concerning. Present insights in simple terms that our sales managers can act on immediately. Always include trend explanations and next steps.

​
What to avoid

  • Contradictory instructions that create confusion about priorities
  • Overly complex rules that are hard to follow consistently
  • Vague guidance like “be helpful” without explaining what that means for your situation
  • Too many different focus areas in one agent, remember to keep each agent focused, split unrelated jobs into separate agents
  • Restating basic features, don’t tell the AI to “create charts” since it already does that
Poor example - Too vague:
Be helpful and analyze data well. Create good charts and explain things clearly.

​
Review instructions regularly

Review instructions after changing business rules or finding a recurring error. Remove duplicate guidance and contradictions, then run representative questions or an evaluation suite to check the effect. Feedback alone does not rewrite the agent’s instructions.