Why Backend Tasks Still Break AI Agents - Tool Response Design Matters

Fazm Team··2 min read

Tool Response Design Is Everything

Here's a pattern that breaks agents constantly: a tool returns 50KB of raw JSON from a database query. The agent's context window fills up with data it can't meaningfully process. It hallucinates conclusions, loses track of its current task, and the whole session derails.

The fix isn't a smarter model. It's a better tool response.

The Rule: Write Full, Return Summary

When a tool executes a query that returns substantial data, it should do two things. First, write the complete results to a file. Second, return a compact summary to the agent.

Instead of dumping 200 database rows into the context, the tool writes them to /tmp/query-results-2026-03-17.json and returns: "Found 200 records. Top categories: billing (87), support (64), feature-request (49). Full results saved to /tmp/query-results-2026-03-17.json."

Now the agent has what it needs to make decisions without burning its context window on raw data. If it needs specific records, it can read the file selectively.

Why This Pattern Matters More Than Model Capability

A model with 1 million tokens of context doesn't solve this problem. More context just means the agent drowns in more data before failing. The issue isn't capacity - it's signal-to-noise ratio.

An agent with 200K context and well-designed tool responses will outperform an agent with 1M context and tools that dump everything into the conversation. Every time.

Designing Good Tool Responses

Good tool responses follow a few principles:

Be specific about counts and categories. "Found 47 errors" is better than returning 47 error messages. The agent can ask for details if it needs them.

Include actionable metadata. File paths where data was saved, timestamps, status codes. Things the agent can use in its next action.

Omit raw data unless it's small. If the response fits in a tweet, return it inline. If it doesn't, save it to a file and return a pointer.

The Broader Lesson

Most "the AI couldn't handle this task" complaints are actually "the tools gave the AI garbage to work with" problems. Model capability is rarely the bottleneck. Tool response design almost always is.

More on This Topic

Fazm is an open source macOS AI agent. Open source on GitHub.

Related Posts