Tool design — results

Read these first

• Tool design — descriptions
• Context engineering — the budget

What you will know

• Return a result shaped for a model rather than for a UI

  UI-oriented envelopes and opaque identifiers consume tokens without giving the model usable evidence or actions.

• Truncate or paginate a large result instead of blowing the window

  A bounded response must preserve the highest-value fields and expose that data is incomplete so the model does not treat a partial view as exhaustive.

• Summarise a payload before it reaches the context

  Preprocessing can retain aggregate facts and relevant exceptions while avoiding the cost and distraction of transmitting every raw record.

• Measure the token cost of a typical tool result

  Count representative worst cases with the production tokenizer, including field names and serialization overhead, rather than relying on byte size.

• Compare offset pagination, cursor pagination, bounded truncation, and pre-summary on a representative payload

  Cursor stability under concurrent writes, ordering requirements, latency, and information loss determine which boundary strategy is safe.

Chapters

1. 1

   Projecting a tool result

   The JSON:API document a web app consumes — data wrappers, type discriminators, relationships, links, meta, and opaque ids standing in for names — spends most of its tokens on structure a model cannot act on. A projection keeps the names, statuses and dates the model will answer with plus the identifiers it will pass to the next call, which took one support tool from 218 tokens per record to 41 and removed twelve follow-up lookups.

   Read chapter
2. 2

   Token cost of a tool result

   Fifty orders in 38 KB of JSON budgeted at roughly 9,500 tokens measure 14,880, because UUIDs, SKUs, hashes and ISO timestamps fragment into short tokens while bytes-over-four was calibrated on English prose. Tokenise representative worst cases with the production tokenizer inside a real tool-result block, count field names and serialisation overhead, and treat the number as a size rather than as a cost or a verdict on quality.

   Read chapter
3. 3

   Declaring a capped result

   A tool that caps at 25 rows and returns them with no marking lets an agent report an absence that is not there. A boolean truncated flag answers one of the four questions the model needs answered: carry the total matched, the number returned, the ordering used and a route to the remainder. Why raising the cap from 25 to 500 removes 97% of the incidents while aiming the survivors at the largest accounts, and where in the stack the contract has to be computed.

   Read chapter
4. 4

   Offset paging and keyset cursors

   LIMIT 50 OFFSET n over a table others are writing to skips rows and repeats others, because an offset counts positions in a result set that is recomputed on every call. A keyset cursor on (updated_at, id) resumes from a position in the data instead, needs a unique tiebreaker and an ORDER BY that matches it exactly, and costs the same at page one hundred as at page one — while still not being a snapshot.

   Read chapter
5. 5

   Server-side rollup of log lines

   An hour of log lines from one service is about 3.96 million tokens, so the tool should return what a reliability engineer's queries return: counts by level, latency percentiles per minute, grouped error classes, and the handful of distinct stack traces verbatim with their occurrence counts. The same reasoning turns 4,000 refund rows into a computed total, a row count and the largest few. A rollup is lossy too, so it owes a basis block and a drill-down call.

   Read chapter
6. 6

   Summarising a payload with a model

   A cheap model between a 40,000-line payload and the tool result buys the one thing a server-side rollup cannot: it handles payloads whose salient content nobody could have written a query for in advance. It costs what aggregation does not — a rollup drops information at a boundary you chose and can state, a summariser drops it non-deterministically, so the same window yields a usable summary on one run and eats the causal line on the next. Keep the raw payload behind a handle, and measure retention with a needle suite.

   Read chapter
7. 7

   Choosing a boundary strategy

   Offset pagination, cursor pagination, bounded truncation and pre-summary each fail differently, and the payload decides which failure you can live with. Weigh cursor stability under concurrent writes, whether an ordering is required at all, added latency, how much information each option destroys, and which of the two pre-summary paths the payload justifies — then apply the comparison to a work queue, a transaction ledger and an hour of logs, which land on three different answers.

   Read chapter