What you will be able to do
- Name the common harness failures (context rot, tool overload, brittle tool wiring, irrelevant retrieval, weak verification, missing guardrails) and match each one to the fix that addresses it most directly
- Tell when a failure needs a prompt or instruction change, and when it needs a different agent structure
- Pick a fix that removes or narrows context instead of adding more
Key concept
The agent harness as the place failures live — The harness is everything around the model: its prompts, the context it gets, its tools, retrieval, memory and verification. When an agent misbehaves, look for the cause in the harness first, because changing the model is rarely the fix that addresses the problem most directly.
1.Start with the symptom, then find the harness component
Exam questions on this skill usually describe a behaviour, not a cause: the agent gives confident wrong answers, stalls before doing anything, loops, or calls a task done when it isn't. Your job is to trace that behaviour to the part of the system feeding the model. Databricks treats prompt engineering and context engineering as parts of a larger discipline: the harness is the system around the model, and prompts and context are pieces of it. So the first question to ask is which piece of the harness put the wrong thing in front of the model, or left the right thing out. Asking whether the model is good enough comes later, if at all.
The Databricks harness article lists the failures teams hit most often in real systems. Learn them as symptom–fix pairs. The table below adds, for each one, the fix the Databricks documentation points to. The tool-overload row shows the general principle behind most of these fixes: the recommended action is to give the agent less, not more. The design guidance says to provide only the tools and context the agent needs, not an unbounded set of APIs or a large amount of irrelevant context.
| Failure | What you observe | Most direct lever |
|---|---|---|
| Context rot | Reasoning quality degrades as conversation history grows on long-running tasks | Trim or summarize older context |
| Tool overload | Confusion and slow decision-making before any work begins | Provide only the tools the agent requires; split a large tool set across agents |
| Brittle tool wiring | Small changes to tool descriptions cause incorrect tool use and silent failures | Log every tool call with MLflow Tracing; run regression tests |
| Irrelevant retrieval | Wrong information is pulled from memory or search, and the model answers confidently but incorrectly | Improve retrieval quality (query, search strategy, re-ranking, filters) |
| Weak verification | Agent stops too early or declares success on incomplete work | Add testing loops or self-checks, e.g. one agent generating, another verifying |
| Missing guardrails | Irreversible actions taken without oversight | Require human approval for risky actions |
| Latency | Multi-step agents take 10 seconds or longer | Combine steps or cache repeated queries |
Checkpoint 1 of 4· Check yourself
An agent has access to forty tools. Before it does any work, it takes a long time to decide what to do, and it often picks an unsuitable tool. Which change addresses this most directly?
These are the symptoms of tool overload, and the fix is to shrink the tool set the agent sees. Longer descriptions or a bigger model leave the confusion in place.
“Giving the model too many tools at once increases confusion and slows decision-making before any work begins.”Source: www.databricks.com
Checkpoint 2 of 4· Exam question
Early in a long-running support session, an agent's tool call returns a customer's account tier as "Platinum" due to a transient bug, when the account is actually "Gold". For the rest of the session, the agent keeps applying platinum-only discounts and referencing the platinum tier in its reasoning, even after a later tool call correctly returns "Gold" in the results. Which context failure mode does this trace illustrate?
Correct answer: A — Context poisoning
- A. Correct. A wrong fact (the erroneous "Platinum" tier) entered the context and was treated as established truth, then repeatedly reinforced and referenced in later reasoning even after correct information appeared — the defining pattern of context poisoning.
- B. Incorrect. Context distraction describes an agent over-focusing on accumulated history (e.g., repeating prior actions) rather than a single hallucinated fact contaminating later reasoning.
- C. Incorrect. Context confusion involves irrelevant content in the context influencing the output; here the problem is a specific incorrect fact being propagated, not irrelevant clutter.
- D. Incorrect. Context clash involves two pieces of contradictory information both being acted on inconsistently; here the agent consistently (and wrongly) sticks with the poisoned fact rather than flip-flopping between conflicting values.
2.When the instructions themselves are the problem
Some failures happen even though the agent has the right data and the right tools, because its instructions mislead it. The Databricks design guidance names the three things a bloated prompt causes: contradictory instructions, distracting information and hallucinations. The fix is to make the prompt clearer and shorter, not to pile more onto it.
The Genie Agents troubleshooting guide shows what instruction-level fixes look like in practice. If the agent misreads business shorthand, for example taking "year" as the calendar year when the business means a fiscal year starting in February, you add instructions that explicitly map the jargon to concepts the agent understands. If it gets timezone conversions wrong, you spell out the source timezone, the conversion function and the target timezone. If it has descriptions available but still uses tables wrongly, example queries are especially effective. If it is being pulled in several directions, you narrow its focus by removing irrelevant tables or instructions.
One more symptom belongs here. Earlier turns in a chat can influence later responses. When you are testing whether a new instruction works, leftovers from the old conversation can hide the result. Starting a new chat gives you a clean context to test against.
Checkpoint 3 of 4· Check yourself
A Genie Agent keeps answering "sales this year" with calendar-year figures, but the company's fiscal year starts in February. What is the most direct fix?
This is business jargon the agent can't know. Databricks says to fix it with instructions that map the jargon to concepts the agent understands.
“include instructions that explicitly map your business jargon to words and concepts Genie can understand.”Source: docs.databricks.com
Start a new chat. Earlier turns in the conversation can influence the agent's responses, so a fresh chat gives you a clean context in which to test the new instructions.
3.When one agent is carrying too much
Some failures can't be fixed by editing a prompt, because the problem is the shape of the system. Databricks lays out a range of designs: LLM plus prompt, deterministic chain, single agent, multi-agent. Its advice is to start simple and add complexity only when the failure requires it.
A single agent is the recommended default. Its failure modes are specific, though. It can repeat tool calls or make incorrect ones, and once its scope covers very different sub-domains such as finance, devops and marketing, it becomes unwieldy or overloaded. The fix for that overload is a multi-agent system: each specialised agent has its own domain, its own context and possibly its own tools, and a supervisor routes requests between them. This is also the structural fix for a tool set too large to fit in one agent's schema, since each agent can own part of it. A second agent can also provide verification: one agent generates an answer and another checks it.
Multi-agent setups bring new failures of their own. Agents can pass a task back and forth indefinitely, and any tool-calling agent can loop. The direct fix there is a hard limit on iterations or time. Adding more agents doesn't help.
Checkpoint 4 of 4· Match them up
Match each observed failure to the structural fix that addresses it most directly
Tap a term, then the definition that fits it.
Each fix acts on the component that caused the failure: loop control, how scope is divided, human oversight, and a verification step.
“Infinite loops can occur in any tool-calling scenario, so set iteration limits or timeouts.”Source: docs.databricks.com
Sources1
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.When an agent gives wrong or degraded answers, the first fix is a larger or newer model.Why is that wrong?
Prompts and context are parts of the harness, which is where most operational failures start. Changing context, tools or verification is usually the more direct fix.
Covered in Start with the symptom, then find the harness component
2.If an agent misuses data despite having instructions, add more instructions and more tables so it has everything it might need.Why is that wrong?
Databricks recommends narrowing the agent's focus by removing irrelevant tables and instructions. Extra material adds distracting and contradictory context.
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“Provide only the tools and context your agent requires, rather than an unbounded set of APIs or large irrelevant context.”
↩︎ Start with the symptom, then find the harness component“Implement detailed logging for each user request, agent plan, and tool call using MLflow Tracing.”
↩︎ Start with the symptom, then find the harness component“Keep prompts clear and minimal to avoid contradictory instructions, distracting information and reduce hallucinations.”
↩︎ When the instructions themselves are the problem“a single agent can become unwieldy or overloaded with functionality requirements.”
↩︎ When one agent is carrying too much“Each agent has its own domain or task expertise, context, and potentially distinct tool sets.”
↩︎ When one agent is carrying too much“You have so many tools that fitting them all into one agent's schema is impractical; each agent can own a subset.”
↩︎ When one agent is carrying too much“one agent generating an answer, another verifying it”
↩︎ When one agent is carrying too much“When building any AI-powered application, start simple.”
↩︎ When one agent is carrying too much“Infinite loops can occur in any tool-calling scenario, so set iteration limits or timeouts.”
↩︎ Checkpoint - 2.https://www.databricks.com/blog/ai-harnessSecondary source
“Without a strategy to trim or summarize older context, performance often breaks down on long-running tasks.”
↩︎ Start with the symptom, then find the harness component“Most operational agent failures come from the harness, not the model itself.”
↩︎ Key concept“Prompt and context engineering both live inside harness engineering.”
↩︎ Exam trap 1“As conversation history grows, the model’s reasoning quality degrades.”
↩︎ Prediction“Giving the model too many tools at once increases confusion and slows decision-making before any work begins.”
↩︎ Checkpoint - 3.
“Include more explicit instructions detailing the original source timezone, the conversion function, and the target timezone.”
↩︎ When the instructions themselves are the problem“Example queries are especially effective for teaching your agent how to use your data.”
↩︎ When the instructions themselves are the problem“starting a new chat gives you a blank starting point for testing new instructions”
↩︎ When the instructions themselves are the problem“Review your instructions and try to focus the agent by removing irrelevant tables or instructions.”
↩︎ Exam trap 2“include instructions that explicitly map your business jargon to words and concepts Genie can understand.”
↩︎ Checkpoint