DEV Community

Datafaro
Datafaro

Posted on

Designing tools for AI agents: why small outputs beat big ones

Most APIs were designed for humans and batch jobs. You ask for data, you get all the data, and you process it later. That works fine for a script. It works badly for an AI agent.

I've been building data tools that agents call through MCP (the Model Context Protocol), and the biggest lesson so far is simple: the shape of your output matters more than the amount of data you return. Here's what I mean, with the rules I now follow.

Why agents are different consumers

When an agent calls your tool, three things happen that don't happen with a script:

  1. Everything you return lands in the context window. A 50 KB JSON response isn't "just data", it's tokens the model has to read, pay for, and keep around for the rest of the conversation.
  2. The agent is waiting, and so is a human. Many MCP clients wait around 30 seconds for a tool call by default. If your tool takes 45 seconds, the agent often gets "still running" instead of an answer, and the user sees a stalled conversation.
  3. The model fills in your inputs. Every extra parameter is one more thing the model can guess wrong.

So a tool that is "complete" in the traditional sense can be a worse tool for an agent than one that does less, faster, with a clearer answer.

Rule 1: Lead with a one-line summary

Every result I return includes a summary field written in plain English, like:

Search interest in "claude" worldwide over the past 12 months is rising, up 299% from the first to the last quarter; it peaked at 28 on 2026-11-08 and averaged 17 on a 0-100 relative scale.
Enter fullscreen mode Exit fullscreen mode

The full time series is still there for anyone who wants to chart it. But in most conversations, the agent only needs that sentence to answer the user. It reads one line instead of 52 data points, and the answer is consistent because I decided how to describe the trend, not the model on the fly.

Rule 2: Flat beats nested

Compare:

{"post": {"author": {"profile": {"handle": "x.bsky.social"}}, "record": {"text": "..."}, "metrics": {"likes": 12}}}
Enter fullscreen mode Exit fullscreen mode

with:

{"author": "x.bsky.social", "text": "...", "likes": 12}
Enter fullscreen mode Exit fullscreen mode

Same information, fewer tokens, and nothing for the model to dig through. I convert raw API objects into flat records with obvious field names before returning them. If a field needs explaining, the name is wrong.

Rule 3: Cap the size by default

Defaults matter more than limits, because agents rarely change them. A search tool that defaults to 1,000 results will return 1,000 results. I default to 10–50 items and let callers ask for more explicitly. For text content (like newsletter posts), full text is off by default and a ~300-character excerpt is on.

Rule 4: Design for the time budget

I aim for a typical call under 10 seconds and a worst case under ~20. That shaped real decisions:

  • Hard per-request timeouts, so one slow upstream call can't eat the whole budget.
  • Returning partial results with a clear flag rather than waiting for perfection.
  • Documenting honestly when something is slow (bulk runs that take 1–2 minutes are fine for automations, not for chat).

One of my tools went from 44 seconds to about 6.5 seconds per call mostly by fixing timeouts and retries, not by making the data smaller. (I wrote about that separately.)

Rule 5: Narrow, forgiving inputs

  • One obvious required input (a query, a URL, a list of keywords).
  • Sensible defaults for everything else, and defaults that always return data. If someone calls the tool with an empty input, they should get a useful example, not an error.
  • Accept what models naturally send. @handle, handle.bsky.social and a full profile URL should all work. A country written as WORLD or left empty should both mean worldwide.
  • Fail softly per item. If one of five keywords has no data, return four results and one clearly marked "no data" item. Don't fail the whole call.

Rule 6: Make errors useful to a model

An error message is a prompt for the agent's next attempt. Compare:

HTTP 400
Enter fullscreen mode Exit fullscreen mode

with:

"XX" is not an ISO 3166-1 country code. Use a 2-letter code like US, GB or ES (use GB for the United Kingdom).
Enter fullscreen mode Exit fullscreen mode

The second one gets fixed on the next try without the user ever noticing.

Rule 7: Price per retry, not per byte

Agents retry. If a tool is expensive per call, every misunderstanding costs real money. I price per query or per result, keep the per-call cost low, and don't charge for failed or empty results. That makes the tool safe to call speculatively, which is exactly how agents use tools.

A checklist

Before shipping a tool for agents, I now check:

  • [ ] Every result has a one-line plain-English summary.
  • [ ] Output is flat, with obvious field names.
  • [ ] Default size is small; bigger is opt-in.
  • [ ] Typical call < 10 s, worst case < ~20 s.
  • [ ] Empty input returns a useful example.
  • [ ] Inputs accept the formats a model is likely to send.
  • [ ] Errors say how to fix the input.
  • [ ] Failed and empty results are free.

None of this is complicated. It's mostly about remembering who your user is: not a script that will dutifully parse whatever you send, but a model with a limited attention span and a human waiting on the other side.

I'm applying these rules in a few small data tools for agents (Google Trends, Bluesky and Substack) published as Apify Actors under Datafaro. If you're building agent tools too, I'd love to hear which rules you'd add.

Top comments (0)