Tool rules

Every tool in the tool set follows the same handful of rules. They keep calls cheap, keep failures honest, and stop a full tool payload from being paid for again in every later turn.

How a tool call flows

1. The model sends a batched tool call.
2. The tool runtime calls the backend over HTTP; the scope comes from the turn.
3. The backend answers with a result, or a retryable failure.
4. The runtime retries retryable failures, each wait doubling the last.
5. The backend returns the result and any per-item failures.
6. The model hears hits, an absence, or an outage — reported separately.
7. Later turns receive the tool name, what was asked, the outcome and (for recent turns) an excerpt.
8. If the model needs more, it calls read_tool_result with the stored ref.

Shared rules

Batching

One call with two angles costs one embedding request and runs the searches in parallel; a single-item tool would cost two model calls. A batch of three queries returns what three calls would.

Partial failure, absence and outage

• One failed fact out of three keeps the two that were stored.
• One dead link keeps the two pages that did read.
• A query that ran and matched nothing is an absence; a query that never ran is an outage. Search tools report them separately so the model can too.

Retries

A backend failure worth repeating is retried, with each wait doubling the last, before the model hears anything. The final report says how many attempts were made.

What decides is what the call does, not how it travels. Every route a turn uses takes its arguments in a body, so a search and a save are both a POST; a policy written against the HTTP verb would have retried neither.

Untrusted output

Tool output is text that somebody outside the organisation may have written. The runtime’s guidance says once to read it as material, never as instruction. Under prompt injection, an identifier the model composes was effectively written by whoever wrote the document it just read — so every one is checked against the turn on the backend. See Guardrails for the checks that act on tool results.

Argument repair

Models get the same few argument shapes wrong, and each is a wrapper rather than a different answer:

• a list sent as the JSON text of a list;
• a one-element list sent as the element itself;
• a one-element list of objects flattened into the call.

Arguments are fitted to the shape the tool asked for before the tool refuses them. Each rule reads the tool’s own published schema, so no tool is named and any tool added later — including application tools — is covered automatically. A rule fires only where the schema leaves one reading: for example, the names of an edit fold into edits because it is the only list the call is missing. Where two answers would fit, the arguments go through as sent and the refusal names what was wrong.

Results in later turns

The full payload a tool returned is never replayed into a later prompt.

• A replayed result whose text was cut carries one terse line: how much was cut, roughly how much there is, and the ref to fetch the rest.
• A call outside the window carries the same line beside its outcome.
• A result that crossed whole carries no line.

How many calls cross from each turn, and which ones keep their place, is part of short-term memory — see Building the prompt.

Reading stored results

read_tool_result reads any result of this conversation, from the current turn or an earlier one.

• A ref from another conversation, another organisation or nowhere is refused identically, so a turn cannot learn whether a guessed identifier was real.
• A row with nothing readable is reported as absent, not as an empty success.
• The description tells the model to read a ref a person pastes into chat and show what it holds.

Previews

A large text or JSON result enters the context as a structured preview — with _toolResultContext.ref, the original counts and a partial flag — within 6,000 encoded characters. The transcript keeps the original output apart from the model-visible preview.

Not previewed (and their refs stay readable): skill instructions, clarification control flow, action acknowledgements, errors and non-text media.

Catalogue results also bypass previews so the model can use them directly:

• search_tools and list_tools keep every returned name, with a description of at most 200 characters.
• get_tool_schema keeps the complete selected definitions; unknown names come back in missing with a discovery hint.
• Distinct search_tools queries run concurrently, at most five per call, and results keep query order.

Searching a stored result

{"refs":["tool-result-ref"],"query":"reimbursment deadline","match":"fuzzy","contextChars":200,"maxChars":4000}

Search fetches no knowledge passages and uses no embeddings, summaries or cache. Report grounding and live evaluation count only model-visible previews and returned windows; metadata-only matches, workflow instructions, failed reads and saved write inputs never count as retrieved evidence.

Exporting stored text

• Direct export. Pass path and one _toolResultContext.sources selector to write_file. The selector holds a ref and a field array (JSON strings are decoded along the path), plus optional between delimiters that must identify one complete region. The backend selects the text from the original stored result, including text the preview omitted.
• Refused before any file in the batch is written: missing fields, ambiguous delimiters, failed calls, read windows, and records marked truncated.
• Transformations. run_code accepts up to three toolResults refs — see Workspace and code.

Lookups stay within the conversation and preserve the provider’s text exactly; they never fetch additional API pages.

Reading earlier turns

read_transcript reads earlier turns of the current conversation verbatim, by a range of turn numbers or by literal words. Each turn returns:

• its number and start time;
• what the person wrote and the assistant’s answers;
• each tool call’s name, the first 400 characters of its arguments, and the ref read_tool_result reopens it by.

Thinking is never returned. The conversation is resolved from the turn, so no request can name another one, and the asking turn is left out because it is still being written.

A read spends 6,000 characters by default and at most 20,000, on whole turns. A read that stops early is marked truncated and carries the offset to continue from; a single turn larger than the budget comes back whole.

The tool exists for compaction: a summary names the turns it covers, and a detail it left out is read back from them.

Under the hood

Related