The Agent Spec
Agent quality comes mostly from three things, and mixing them is the most common cause of poor answers. Keep them in separate layers, and let tool descriptions do the heavy lifting on routing.
Start with Three Layers and work through the tabs in order. Next exhibit: Exhibit C, Evaluations.
The Three-Layer Model
Agent quality comes mostly from three things, and mixing them is the most common cause of poor answers. Keep them in separate layers.
Orchestration
Put here: tool routing, intent defaults (e.g. default time window), scope limits, multi-step workflows, fallback when a tool errors or returns nothing.
Keep out: tone, formatting, SQL-generation rules.
Response
Put here: tone, answer-first structure, tables vs. charts, units/currency, data freshness, handling ambiguity or empty results.
Keep out: tool routing, SQL-generation rules.
Tool description
Put here: what the tool does, what data it accesses, when to use it, when NOT to use it, input guidance.
Tool Descriptions Drive Routing Accuracy
Agents pick tools by name and description alone, not by inspecting your data model. This is the single biggest lever on routing accuracy. Write every description with this formula:
Give every tool a distinct domain and a non-overlapping "when to use", and always include an explicit "when NOT to use". When you have multiple Analyst tools, the descriptions are what let the agent tell them apart.
Failure Patterns & Fixes
When an agent misbehaves, the cause is usually one of a few things, and the fix is almost always in the tool description.
| Symptom | Likely cause | Fix |
|---|---|---|
| Wrong tool selected | Vague "When to use" | Add specific examples + "When NOT to use" |
| Parameter errors | Ambiguous inputs | Add format, examples, constraints |
| Hallucinations | Agent using the wrong tool | Tighten negative routing in the description |
Diagnosing routing problems is exactly what evaluations are for. See Exhibit C for measuring tool selection and execution accuracy.
Where the Spec Lives (and How It Deploys)
dbt Projects on Snowflake has no runtime file read, so each agent's spec lives inline in a deploy_<agent> wrapper macro in agents/<agent>.sql. The wrapper passes the spec to create_agent / alter_agent, which substitute the environment tokens with the active target, so the same spec deploys to dev, staging, or prod unchanged.
{% macro deploy_example_agent(alter=false) %}
{% set spec %}
models: { orchestration: auto }
instructions:
orchestration: "routing + defaults + fallbacks"
response: "tone, tables vs charts, units"
sample_questions: [ ... ]
tools:
- tool_spec:
name: sales_analyst
description: "what + when + when NOT + inputs"
tool_resources:
sales_analyst:
semantic_view: <<DATABASE>>.<<SCHEMA>>.SV_SALES
execution_environment: { type: warehouse, warehouse: <<WAREHOUSE>> }
{% endset %}
{{ create_agent('example_agent', spec) }}
{% endmacro %}cortex_analyst_text_to_sql tool needs an execution_environment under tool_resources (the warehouse its SQL runs in). Use execution_environment: { type: warehouse, warehouse: <name> }, not a top-level warehouse key.Deploy with dbt run-operation deploy_<agent> (CREATE OR REPLACE). For zero-downtime edits to a live agent, add --args '{alter: true}'.