Deferred tools

Large tool catalogues add input tokens to each model request. Deferred loading keeps selected tools in the prompt and makes the rest available through discovery. Configure toolLoading on the agent and pin frequently used tools with deferLoading: false.

export default defineAgent({
  agent: {
    slug: "research-agent",
    model: { provider: "gateway", model: "anthropic/claude-sonnet-4.6" },
    system: "…",
    // eager | deferred | auto. `auto` is the default and defers only once the
    // resolved catalogue passes `autoThreshold`, so a small agent pays nothing.
    toolLoading: { mode: "auto", autoThreshold: 12 }
  },
  tools: [
    tool({
      name: "read_source",
      description: "Read a source document by its ID",
      deferLoading: false,               // the one it reaches for constantly: pin it
      input: z.object({ sourceId: z.string() }),
      handler: readSource
    }),
    tool({ name: "list_collections", description: "…", handler: listCollections })  // discoverable
  ]
})

Everything not pinned becomes reachable through three tools Cereal presents instead: one that searches the catalogue, one that describes what it found, and one that runs a small program calling them. Each of those inner calls is still a real, logged, signed, gated call to your handler. Only the presentation differs, and you write your tools exactly as before.

Descriptions become the search index

Discovery searches tool descriptions and signatures. Describe the action and its inputs, such as “Find a parcel's current location by tracking number.” Avoid generic labels that do not help the model distinguish one tool from another.

In the transcript

A call dispatched from inside a plan carries parentToolCallId, and the control plane's transcript nests it inside the plan's card. The three plan tools render as what they are, rather than as JSON: a query and its hits, some names and their schemas, a script and its steps.

Context and caching

Discovery keeps the model-facing tool array stable during the session, helping preserve prompt cache reuse. The discovery calls and results still use tokens. Check usage to compare the cost for your tool catalogue.