The Tool Protocol and the Read-Only Trio: Schema Design, Chunk Merging, and Result Truncation

Today's Goals

1. Write a description and JSON Schema for a tool that a model can genuinely use correctly, and explain what belongs in the description and what doesn't
2. Correctly merge tool-call chunks that arrive via streaming, and explain why you can't assume the index starts at zero
3. Design a result-truncation strategy that keeps key information without blowing up the context

Today is the course's turning point: the Agent decides for the first time what to look at next. When you finish, scroll back up and tick the three goals off.

Plain-Language Walkthrough

Read access first: browse the code, do not touch it

What do you give a new hire on day three? Read access to the repository, probably: browse code, search functions, read tests, but no commits yet. Nearly every team does this, for a plain reason — reads are reversible, writes are not. Read the wrong file and you waste five minutes; edit the wrong file and you may cause a production incident.

An Agent is identical, and needs the step even more, because reading starts from zero for it. For two days it had no tools, so asking "why is this repository's test red" left it guessing — it could not see your files. With three tools it walks a path of its own: list the files, search a suspicious function name, read that implementation, then conclude.

The day deserves its own slot because the tool layer's interface is fixed today, and every tool of the next eighteen days (editing files, running commands, connecting MCP, loading Skills) takes the same shape. Get it wrong today and you pay interest daily. Three things need fixing: how a tool is described to the model, how the model's call request is caught, and how a tool's result is sent back. Each has a trap, matching today's three sections.

In that diagram we completed only the "model produces text" half yesterday. Today fills in the other half: the model requests a tool, we execute it, append the result as a new message, and send again — until it stops asking. That closed loop is the whole of an Agent; the other twenty days add constraints to it.

Three parts of the tool protocol: name, description, parameter schema

When a tool is presented to a model, only three things are visible: the name, a natural-language description, and a JSON Schema for the parameters. It knows nothing of the implementation.

That has a direct corollary people get backwards on their first tool: the description is written for the model, not for the maintainer. So it should say when to use the tool, how to fill the parameters and what the limits are, not that "this function reads via a stream internally."

export const globTool: ToolDef = {
  name: 'glob',
  // Three things in a description: what it is for, what the syntax looks like, what the limits are
  description:
    'List files in the working directory by wildcard, returning relative paths. ' +
    'Supports ** across directories, * for any characters at one level, ? for one character, ' +
    'for example **/*.js or test/**/*.test.js. Skips node_modules and .git automatically.',
  parameters: {
    type: 'object',
    properties: {
      pattern: { type: 'string', description: 'wildcard, e.g. **/*.js; omitted means **/*' },
      limit: { type: 'integer', description: 'maximum entries returned, default 200' },
    },
    required: ['pattern'],
    additionalProperties: false,
  },
  readOnly: true, // D5's approval gate uses this field to decide whether to ask first
  async run(args: unknown, ctx: ToolContext): Promise<ToolResult> {
    // The model cannot see the implementation, so nothing here affects whether it calls correctly
  },
}

GLOB_TOOL = ToolDef(
    name="glob",
    # Three things in a description: what it is for, the syntax, the limits
    description=(
        "List files in the working directory by wildcard, returning relative paths. "
        "Supports ** across directories, * for any characters at one level, ? for one "
        "character, for example **/*.js or test/**/*.test.js. Skips node_modules and .git."
    ),
    parameters={
        "type": "object",
        "properties": {
            "pattern": {"type": "string", "description": "wildcard, e.g. **/*.js; omitted means **/*"},
            "limit": {"type": "integer", "description": "maximum entries returned, default 200"},
        },
        "required": ["pattern"],
        "additionalProperties": False,
    },
    read_only=True,  # D5's approval gate uses this to decide whether to ask first
    run=run_glob,
)

Four rules of thumb, all directly copyable:

1. Name it verb plus noun: short, lowercase, underscore-separated. Models understand read_file far more reliably than fileReader, because tool names in training data mostly look like that.
2. Put examples in the description. A model's memory of wildcard and regex syntax is less reliable than you think, and one **/*.js example saves two rounds of trial and error.
3. Give every parameter a description, including its default. The words "default 200" make the model simply omit the parameter when it does not need a limit.
4. Do not stuff two jobs into one tool. A "read a file or list a directory depending on whether path is a file" design gets used wrongly half the time. Two tools are better.

One field is for us rather than the model: readOnly. All three of today's tools are read-only, so it looks useless; day five's approval gate uses it to distinguish "pass straight through" from "ask first." Fixing the field today is far cheaper than adding it to every tool on day five.

The real shape of a streamed tool call: only valid JSON once joined

Now look at the model's call request. This is where documentation misleads beginners most — the documented example is the complete non-streaming structure, while what you receive in streaming is chopped up.

One stream carrying a tool call, with the outer wrapper removed, measured on 7 September 2026 (one call split into six to twelve fragments), looks roughly like this:

{"index":1,"id":"call_abc","function":{"name":"glob","arguments":""}}
{"index":1,"function":{"arguments":"{\"pat"}}
{"index":1,"function":{"arguments":"tern\":\"**/"}}
{"index":1,"function":{"arguments":"*.js\"}"}}

Four regularities, each of which bites:

1. The id and the function name appear only in the first fragment, and later fragments carry only argument increments. So merging must not overwrite; write only when a value is present.
2. The arguments are a chopped-up JSON string that is valid only once joined. Which is why yesterday's type has ToolCall.args as a string, not an object — parsing must happen after joining.
3. Split points are arbitrary, landing inside a quote or inside an escape sequence. Any "try parsing on every fragment" approach yields a run of failures.
4. The finish reason is a dedicated value (tool calls rather than a normal stop). But do not trust that field alone: we measured models reporting a normal stop while still emitting tool fragments, and reading only the field treats that turn as finished. The safe criterion is "the finish reason is tool calls, or at least one call was merged."

The index does not start at zero: a trap we measured

Merging depends entirely on a fragment's index. Which produces the error everyone makes once: assuming the index starts at 0 and storing by array subscript.

That is not a theoretical risk. On 7 September 2026, on the same gateway (https://api.n1n.ai/v1), with the same model (claude-haiku-4-5-20251001) and the same code, two runs of a parallel tool call returned these indexes:

first run:  index = 1, index = 2
second run: index = 0, index = 1

Same day, same gateway, same model, same code, two starting points. So the correct conclusion is not "vendor X starts at 1" but that the starting point cannot be assumed — we merely measured two of them. It is an opaque identifier whose only dependable property is that fragments of one call share one index.

Pushing in arrival order is worse, because parallel calls' fragments interleave: the second call's head may arrive before the first call's head, and then their argument fragments alternate. Joining in arrival order stitches two calls' arguments into one.

export class ToolCallAccumulator {
  /** A Map rather than an array: the index may start anywhere and may not be contiguous */
  private readonly byIndex = new Map<number, Partial>()
 
  push(delta: { index: number; id?: string; name?: string; argsDelta?: string }): void {
    const slot = this.byIndex.get(delta.index) ?? { index: delta.index, args: '' }
    if (delta.id) slot.id = delta.id // only in the first fragment, so write only when present
    if (delta.name) slot.name = delta.name
    if (delta.argsDelta) slot.args += delta.argsDelta // arguments accumulate, never overwrite
    this.byIndex.set(delta.index, slot)
  }
 
  /** Drain in index order, not arrival order: parallel calls' fragments interleave */
  drain(): ToolCall[] {
    return [...this.byIndex.values()]
      .sort((a, b) => a.index - b.index)
      .map((slot, position) => ({
        id: slot.id ?? `call_${slot.index}_${position}`, // give one even if the id is missing
        name: slot.name ?? '',
        args: slot.args,
      }))
  }
}

from dataclasses import dataclass, field
 
 
@dataclass
class ToolCallAccumulator:
    # A dict rather than a list: the index may start anywhere and may not be contiguous
    by_index: dict[int, dict[str, str]] = field(default_factory=dict)
 
    def push(self, delta: ToolCallDelta) -> None:
        slot = self.by_index.setdefault(delta.index, {"args": ""})
        if delta.id:
            slot["id"] = delta.id             # only in the first fragment, so write when present
        if delta.name:
            slot["name"] = delta.name
        if delta.args_delta:
            slot["args"] += delta.args_delta  # arguments accumulate, never overwrite
 
    def drain(self) -> list[ToolCall]:
        # Drain in index order, not arrival order: parallel fragments interleave
        return [
            ToolCall(
                id=slot.get("id") or f"call_{index}",  # give one even if the id is missing
                name=slot.get("name", ""),
                args=slot["args"],
            )
            for index, slot in sorted(self.by_index.items())
        ]

Argument parsing failures are normal: feed them back, do not throw them at the user

Once joined, parse. Here comes a shift in mindset, the biggest difference between a Coding Agent and an ordinary backend service:

A parse failure is not an exception, it is a normal return value.

An ordinary service that receives an illegal parameter throws a 400 and is done — the caller is a program and will fix it next time. An Agent's caller is a model, writing by guesswork: it omits required parameters, writes numbers as strings, invents tool names. The correct handling is to hand the error back verbatim and let it fix itself — just as, when a new hire submits code that will not run, pasting the error to them beats fixing it for them.

So the tool execution entry point has a hard rule: always return a result, never throw. Four situations all translate into a failed result:

The fed-back text must be specific enough to act on. "Operation failed" is useless; "there is no tool named edit_file. Available tools are: glob, grep, read_file" is useful — the model reads it and takes another route. The lab shows this directly: have the offline script invent an editing tool that does not exist yet, and the terminal reads:

> edit_file({"path":"src/calc.js","old":"a / b"})
x edit_file fed back 45 chars - there is no tool named edit_file. Available: glob, grep, read_file
So there is no editing tool today, only three read-only ones. Let me read the code first.
> read_file({"path":"src/calc.js"})
v read_file fed back 248 chars - src/calc.js (lines 1-13 of 13)

Two invariants remain; miss either and the next request is invalid, and most gateways reject it outright: the assistant message must carry the calls it requested, and every call must have exactly one corresponding result message — even a failed one. Day six's error classification returns here; today, just establish the never-throw discipline.

Each read-only tool's boundary

Three tools, each with one place that causes trouble if left unbounded.

read_file: how much to read. Default to four hundred lines, not the whole file. Stuffing a whole file into context is the most common waste, and the model usually knows where to look from the opening. Two more details: output line numbers (the model locates by them, and tomorrow's editing tool talks in them too), and truncate any single line over five hundred characters (one line of minified JS can run to hundreds of thousands). On a binary file, say so explicitly instead of feeding garbage back.

glob: what to exclude. Skip directories like node_modules, .git and dist while walking, or one call returns ten thousand files, all noise. Cap results at two hundred and tell the model how many were withheld — otherwise it believes it saw everything and reasons on a false premise. An empty result should also state how many files the working directory holds in total, helping it tell "nothing there" from "I wrote the pattern wrong."

grep: bound all three dimensions. Match count (default fifty), line length (one hundred and twenty characters), and file scope (an optional wildcard parameter; narrowing first is far cheaper than filtering afterwards). Fix the output format as path, colon, line number, colon, content, because that is the shape the model has seen most and it can call read_file from it directly.

All three share one boundary: every path must stay inside the working directory. The model receives relative paths and will try to climb out — not out of malice, but because it is guessing. The only valid criterion is whether the resolved absolute path is still inside; scanning the string for two dots is unreliable. Remember to append a separator to the root when comparing, or a sibling directory with the same prefix is wrongly judged inside.

In the lab, asking "look at this repository and tell me why the tests are red" walks the offline script through glob, grep and read_file, feeding back 50, 361 and 248 characters respectively — three reproducible numbers, because the sandbox repository is generated deterministically.

Result truncation: cut from the middle, keep both ends, and say how much was cut

The last thing, and the most overlooked: tool results are fed back into the message array, and the whole message array is resent every turn.

That sentence needs arithmetic to feel. A grep matching two thousand lines, roughly sixty thousand characters, is paid for as input tokens not just this turn but every turn after; five turns is five payments. Worse, it squeezes out the context that matters — the user's request, the key code read earlier.

So set a ceiling for a single tool result. This course fixes it at eight thousand characters, with three rules:

export const MAX_RESULT_CHARS = 8000
const HEAD_RATIO = 0.6 // more head: the most relevant content is usually at the front
 
export function truncateResult(result: ToolResult): ToolResult {
  const text = result.content
  if (text.length <= MAX_RESULT_CHARS) return result
 
  const head = Math.floor(MAX_RESULT_CHARS * HEAD_RATIO)
  const removed = text.length - MAX_RESULT_CHARS
  // The middle note is for the model: it cannot read an ellipsis but can read an instruction
  const note = `\n...(${removed} characters truncated from the middle; ${text.length} characters in total; read again with an offset for the middle)...\n`
 
  return {
    ...result,
    content: text.slice(0, head) + note + text.slice(text.length - (MAX_RESULT_CHARS - head)),
    // Truncation itself is for humans and need not spend the model's tokens: meta is not fed back
    meta: { ...result.meta, truncated: true, originalChars: text.length },
  }
}

MAX_RESULT_CHARS = 8000
HEAD_RATIO = 0.6  # more head: the most relevant content is usually at the front
 
 
def truncate_result(result: ToolResult) -> ToolResult:
    text = result.content
    if len(text) <= MAX_RESULT_CHARS:
        return result
 
    head = int(MAX_RESULT_CHARS * HEAD_RATIO)
    removed = len(text) - MAX_RESULT_CHARS
    # The middle note is for the model: it cannot read an ellipsis but can read an instruction
    note = (
        f"\n...({removed} characters truncated from the middle; {len(text)} in total; "
        "read again with an offset for the middle)...\n"
    )
 
    return replace(
        result,
        content=text[:head] + note + text[-(MAX_RESULT_CHARS - head) :],
        # Truncation is for humans and need not spend the model's tokens: meta is not fed back
        meta={**(result.meta or {}), "truncated": True, "originalChars": len(text)},
    )

The three rules, explained. One: cut from the middle, never keep only the head — the tail often holds the conclusion: the last line of an error, a test summary line, a file's export list. Keeping only the head throws the conclusion away, and it is the most common wrong approach. Two: state how much was cut and how to fetch the middle next; the model cannot read an ellipsis but can read an instruction. Three: put the fact of truncation in meta, for terminal rendering only, not fed back to the model.

One design choice too: truncation lives at the tool execution entry point, not inside each tool. Tool authors only get the content right, and the context budget is managed in one place — otherwise, twenty days later, fifteen tools each carry their own truncation logic.

The lab's self-test shows two reproducible numbers: a twenty-thousand-character fake result truncated to 8054 characters (the eight-thousand ceiling plus the note), stating that 12000 characters were cut; and having the model read a generated file of over thirty-eight thousand characters, which likewise feeds back 8054. How the total context budget is split between the system prompt, the history and tool results is day twelve's subject — today handles one thing only: no single result may be unbounded.

Source Reading

Hands-On Lab

Today's lab spins the loop for real for the first time. The starter leaves three exercises, matching the three easiest mistakes in this chapter: fragment merging, illegal-argument feedback, and result truncation. Unmodified it passes two of seven.

1. Define the tool registry and one unified execution entry point, so the loop knows only "list" and "execute" and no concrete tool.
2. Implement the three read-only tools, each with parameter validation and limits; share one path-boundary check across all three and confirm climbing out of the directory is blocked.
3. Merge tool-call fragments into complete calls by index, feed illegal arguments with INJECT=bad_args, and confirm it becomes a failed result fed back rather than a thrown stack.
4. Add truncation to tool results: over eight thousand characters, cut from the middle, keep both ends and state how much was cut.
5. Run the self-test: MOCK=1 SELFTEST=1 pnpm start should print 7/7 passed, with the call order and the truncated character count both reproducible numbers.

Acceptance is five ticks: the self-test prints 7/7 passed; one question shows glob, grep and read_file cards in order followed by a conclusion; interleaved fragments starting at index 1 merge into two calls; a twenty-thousand-character result truncates to 8054 characters stating 12000 were cut; and INJECT=bad_args lets the loop finish with exit code 0.

Interview Questions

Today's three questions are all of the "you can answer only if you implemented it" kind:

1. How should a tool's description and JSON Schema be written so the model makes fewer mistakes?
2. How do you merge tool-call arguments arriving via streaming? What assumptions are forbidden?
3. When a tool result far exceeds the context budget, what is your truncation strategy? How do you avoid cutting the key information?

Full bilingual prompts, analyses and key points are in this course's day-three question bank. Question two discriminates most in this course — anyone who has not merged fragments themselves cannot answer "what you must not assume," which is exactly the half-sentence the interviewer wants.

Checklist and Tomorrow

• I can name the three things the model can see, and what does and does not belong in a description
• I can explain why the arguments are a string rather than an object, and when parsing should happen
• I can explain why the index's starting point cannot be assumed, and what is wrong with joining in arrival order
• I can list the four situations translated into failed results, plus the two message invariants
• I can name each read-only tool's bounded dimension and state the path-boundary criterion
• The self-test prints 7/7 passed, and I know where the number 8054 comes from

Tomorrow is D4, "File Editing and Shell Execution: Exact Replacement, Conflict Detection, and Killable Child Processes on Timeout," where read access becomes write access. The risk changes by an order of magnitude, so tomorrow's focus is not how to put characters into a file but three failure modes: the old content does not match, the file changed externally, and a command hangs without returning. The order is deliberate — with reading solid today, the model can confirm that what it is about to change really looks the way it thinks; and by the end of tomorrow it will turn the sandbox repository's failing test green for the first time.