Skip to content
be-human.ai
← Back to the journal

Harness fundamentals

Tool Result Truncation for AI Agents: Keep the Fields That Decide

How to shorten oversized tool outputs in an AI agent harness while keeping the status, identifiers and error fields that decide the agent's next action.

Be Human typographic cover with the title: Tool Result Truncation for AI Agents: Keep the Fields That Decide
Conceptual illustration created with AI · Be Human

Tool result truncation is the step where a harness shortens a tool's output before the model reads it, so the context stays small enough for the agent to reason well. A sound rule keeps the fields that decide the next action, such as status, identifiers, error messages and continuation handles, and removes the bulk around them. The harness should never drop those decision fields silently, and every cut should leave a visible note that says what was omitted and how to fetch it.

Key takeaways

  • Truncate by field role, not by raw character count.
  • Keep status, identifiers, errors and continuation handles in every result, whatever the size.
  • Mark every cut with a visible note and a retrieval path, so the agent can ask for more.
  • Test truncation against the decisions the agent must make, not against how short the output looks.
  • Store the full raw result outside the agent's context so a reviewer can check what the agent saw and what it missed.

Why oversized tool outputs break agent decisions

When an agent calls a tool, the result lands in its working context and competes with the instructions, the task and the history of what the agent already did. A search across a large records system can return far more text than the next step needs. As the context fills, cost and latency rise, and the model has more long, repetitive text to weigh against the short line that actually matters, such as a status flag sitting near the bottom of a log. A common default in simple harnesses is to cut from the end of the output, which is exactly where final statuses, totals and error codes often appear.

The failure is quiet. The agent does not crash. It continues with a partial picture and takes an action that looks reasonable from what it saw. This is why truncation belongs in the harness design rather than in an afterthought. The harness decides what the model sees, so the harness owns the consequences of what it hides.

Which fields decide the next action?

Before writing any truncation code, list the decisions each tool supports and the fields those decisions depend on. Most tool results fall into a small number of groups.

  • Identity fields: the record ID, account, order number or document reference the agent will reuse in later calls.
  • State fields: the current status, the stage, the time of the last change and any flag that gates the next step.
  • Error fields: error codes, failure reasons and retry hints, which should never be shortened into a vague summary.
  • Continuation fields: cursors, page tokens and total counts, so the agent knows whether it saw everything.
  • Ownership and permission fields: who the record belongs to and whether the agent may act on it.
  • Bulk content: long descriptions, full message bodies, raw logs and repeated line items, which can usually be shortened or moved out of context.

Keep the first five groups whole. Bulk content is where truncation should work hardest. A useful test: if removing a field would change which tool the agent calls next, or whether it calls one at all, that field is a decision field.

Which methods keep the decision fields?

Several methods work, and most production harnesses combine them. Field projection returns only the fields a given task needs, which is often the simplest and most reliable approach because the rule is visible in the tool definition. Record limiting returns the first page, the total count and a cursor, so the agent can see that more exists. For logs and long text, keep the opening lines for context and the closing lines for final state, and pin any line that matches an error pattern even when it sits in the middle.

Summarizing is tempting but needs care. A summary produced by a model is a second, lossy step, and it can drop an identifier or soften an error. If you summarize, keep the raw output in storage, place identifiers and status in plain fields beside the summary, and never let the summary replace them. Anthropic's guidance on writing tools for agents makes a related point: returning fewer, higher-signal results and letting the agent ask for detail usually works better than returning everything and hoping the model finds the right part.

Give the agent a way to ask for more. A truncated result that names a follow-up call for the full record is far safer than one that simply ends. The agent can then decide whether the older history matters for the question in front of it.

Step-by-step plan for your harness

Use this sequence for each tool your agent can call.

  • Step one: write down the decisions the tool supports and the fields each decision reads.
  • Step two: mark each field as decision, identity, error, continuation or bulk.
  • Step three: set a projection that always returns the decision fields, regardless of output size.
  • Step four: define a size limit for bulk fields, with a fixed order for what gets cut first.
  • Step five: add a visible truncation note that states what was omitted, the total count and the follow-up call.
  • Step six: store the full raw result outside the agent's context, linked to the run ID.
  • Step seven: write test cases with oversized results where the decisive field sits at the end, in the middle and inside a nested object.
  • Step eight: log every truncation event with the tool name, original size, returned size and whether an error field was present, so reviewers can spot patterns.

Keep this plan in version control next to the tool definition. When a tool's response format changes, the truncation rule should change in the same review, not weeks later when someone notices a wrong answer.

Illustrative scenario: a refund question

Illustrative scenario: a support agent is asked whether a customer's refund has cleared. The order history tool returns several hundred lines, and the refund state sits in the final record. A naive harness keeps the first two thousand characters and cuts the rest. The agent sees an order and a payment, and concludes the refund is still pending, when it actually completed. It then opens a duplicate refund request.

A harness with field rules behaves differently. It returns the order ID, the current refund state, the timestamp of the last state change, any error from the payment step and a cursor for older history. It adds a note that older events were omitted and names the call that retrieves them. The agent reads the completed state, answers correctly, and requests the older history only if the question needs it. The difference is not the amount of text. It is which fields survived the cut.

Where Be Human's managed approach fits

Be Human treats the shape of tool results as part of the agent's operating context, not as a detail left to each integration. In a first engagement, the team maps the decisions each agent role must make, names the fields those decisions depend on, and agrees the truncation rules with the business owner before anything goes live. Managed operations then keep those rules current. Permission and integration reviews catch changed response formats, recurring evaluations run oversized and edge-case results through the agent, and incident response examines any action taken on a truncated result. The goal is an agent the team can inspect, not one that quietly works from partial information.

How do you test truncation, and where should you start?

Test truncation the way you test the agent: with cases that contain the decision, and with the decision placed where a naive cut would remove it. Keep a small set of oversized results from real tool calls, with personal data removed, and rerun them whenever the tool or the rules change. The OpenTelemetry observability primer is a useful reference for the signals you need, such as result sizes, cut counts and error presence, recorded without storing sensitive content in traces. Treat tool output as untrusted text as well. The OWASP prompt injection guidance notes that content returned to a model can carry instructions, so truncation should never promote a line from the middle of a result into something the agent treats as an instruction. For related controls, read about token and step budgets for agents and AI agent checkpoints and resume.

If you are not sure which tool in your business deserves this work first, take the free Be Human AI diagnostic to find the first task worth handing to an agent.

Frequently asked questions

How much should a harness truncate tool results? There is no universal limit, and a fixed size cap is the wrong starting point. Set limits per field role, so decision fields are always returned and bulk content is the only thing that shrinks. Adjust the limits when evaluations show the agent missing information it needed.

Should the model summarize large tool results instead of truncating them? Summaries can help with long narrative text, but they are lossy and can drop identifiers or soften errors. Keep the raw result in storage, return the decision fields as plain values beside any summary, and make sure the summary never replaces them. Use the summary as context for reading, not as a source of record.

What should happen when the agent needs the part that was cut? The truncated result should name the follow-up call that returns the full record or the next page, along with the total count. The agent then requests what it needs, and the harness logs that request. This keeps the default context small without making the omitted data unreachable.

Who should own truncation rules in a company? The people who understand the business decisions should define which fields matter, and engineering or the managed operations team should implement and version the rules. Review them whenever a tool's response format changes or a new permission is granted. Treat the rules like any other operating control, with a named owner and a record of each change.

Your next step

See where an AI agent fits in your company first.

Take the free Be Human AI diagnostic. A few questions about your work show which task to hand to an agent first, what it needs to know and where a person approves.

Be Human editorial guidance. Examples are illustrative unless explicitly attributed. Sources provide background; implementation choices depend on your workflow.

Less busywork. More room for you.

Bring us the work you wish you had time for.

Book a call to try a personalized AI agent free for 7 days ↗Or take the free AI diagnostic →