Skip to main content
The reasoning trace and tool call logs show what an Atlas AI agent did for any given response: which tools it called, in what order, what each tool returned, and how the agent used those results. Both are available in Atlas AI for every agent response. Reviewing traces regularly is an important part of running agents in production. An agent that calls multiple tools in sequence can produce a response that looks correct but relies on incomplete or wrong data at one of those steps. The final output alone does not tell you whether the reasoning was sound.

​
Reading the reasoning trace

Every agent response includes a reasoning field that shows the agent’s step-by-step decision-making process. Expand the reasoning field in Atlas AI to see how the agent interpreted the user’s question, which tools it selected, and how it combined the results. Use the reasoning trace to answer these questions.
  • Did the agent load the correct skill for this question?
  • Did the agent call the tools you expected, in the order the skill specifies?
  • Did the agent filter on the correct fields and values?
  • Did the agent use the right operation (for example, aggregate_instances rather than list_instances) when the question asked for a count or summary?

​
Reading tool call inputs and outputs

Each tool call in the reasoning trace includes the input the agent sent and the output the tool returned. Select a tool call to expand it and review both. Tool call inputs show you how the agent translated the user’s question into an action. Check these points.
  • Are the filters correct? For example, if the user asked for high-priority work orders, confirm that the agent filtered on priority = 1 rather than on a text value like "HIGH".
  • Did the agent query the correct view?
  • Are the fields in the response the ones you need?
Tool call outputs show you what CDF returned. If the output is empty or missing expected data, the issue may be in the data model rather than the agent’s configuration.

​
Common patterns in agent traces

These patterns appear in agent traces when a configuration needs adjustment.

​
Agent calls the wrong tool

When tool sequencing instructions are absent or unclear in a skill, the agent selects a tool based on the question alone rather than following a documented workflow. Adding explicit sequencing to the relevant skill, specifying which tool to use first and why, gives the agent clearer guidance for questions that involve multiple tools.

​
Agent repeats the same tool call

When a tool returns no results, some agents retry the same call rather than reporting the absence. A skill instruction that tells the agent to surface empty results rather than retry prevents this loop.

​
Agent counts records manually instead of aggregating

When a skill or instruction does not specify how to handle count questions, the agent may retrieve all instances and count them manually rather than using aggregate_instances. A vocabulary mapping that defines “how many” as a signal to aggregate server-side routes these questions to the correct operation.

​
Agent filters on a property that does not exist

When property names in a skill or instruction do not match the actual schema because the schema changed or was assumed, the agent constructs queries that return nothing or produce an error. Using get_view_schema to verify property names before querying an unfamiliar view, or including explicit property names in the skill’s data model guidance, prevents this.

​
Agent makes several calls that could be one

When query guidance in a skill is too granular, the agent follows each instruction step literally rather than consolidating. Simplifying the guidance to describe the goal and the relevant view, rather than each individual operation, typically resolves this.

​
Tracing and evaluation

Tracing and evaluation serve different purposes and can work well together. Tracing shows you what the agent did for a specific response. Use it when a single response is wrong or unexpected and you need to understand why. Evaluation runs a set of test cases against the agent and compares responses to expected outputs. Use it to check that a configuration change improved the responses you intended to improve and did not break other question types. After you identify an issue with tracing and update the agent’s skills or instructions, run your evaluation test cases to confirm the fix before publishing.

​
Response citations

Every Atlas AI agent response includes citations that link the answer back to the data sources the agent used. The product includes citations that appear automatically. You do not need to configure them in instructions or skills. Where tracing shows the full reasoning chain for debugging, citations surface the key sources directly in the response so you can check the underlying records without inspecting the trace.
Last modified on June 18, 2026