How to Build a Multi-Step Agent in Dust with Custom Tools

November 16, 2026

Once a Dust assistant can answer from documents, the next bottleneck is data that is not in a document — order status, inventory, ticket state. That is what custom tools solve. You describe an HTTP endpoint in a schema, and the agent decides when to call it.

This walkthrough builds an agent that checks an order API and falls back to policy documents when the answer is not a lookup.

What is a tool in Dust terms?

A tool is a JSON-schema-described function the model can call. Dust supports several types: HTTP request tools, MCP servers, and built-in ones like web search and document retrieval. The model chooses among them per turn.

That means your job shifts from writing prose instructions to writing a schema the model can reason about. A vague description produces a tool the model calls at the wrong time.

How do you define the HTTP tool?

Create a tool of type HTTP, then fill in four parts:

  • Name — get_order_status. Verb plus noun. The model reads this first.
  • Description — one sentence on when to call it and when not to: “Returns shipping status for a single order ID. Use only when the user provides an order number; do not use for returns eligibility.”
  • Parameters — order_id as a required string with a pattern like ^ORD-[0-9]{8}$. The pattern matters; it stops the agent from passing prose into the endpoint.
  • Request — GET to https://api.yourco.com/v1/orders/{order_id}, with an auth header stored as a workspace secret.

Strip the response. If your API returns 40 fields, map it in the tool config to the six the agent needs: status, carrier, tracking number, estimated delivery, last scan date, and refund state. Every extra field is tokens and confusion.

How do you chain it with document retrieval?

One instruction block, ordered by priority:

  1. If the user supplies an order ID, call get_order_status first.
  2. If the order is marked refunded, search the returns policy documents before explaining.
  3. Answer using tool output and document text only; state which one you used.
  4. If neither covers it, say what is missing.

The ordering in the instructions is guidance, not control flow. Models skip steps. Test the failure mode deliberately: ask a question the document source answers only, confirm the agent does not call the order API anyway. If it does, tighten the tool description — the model is choosing based on the name and description, not your numbered list.

How do you handle errors and partial failures?

Design tool responses so failure is informative. Return HTTP 200 with a JSON body like {"found": false, "reason": "no order with that id"} rather than a 404 with an HTML error page. The model reads the body and can respond sensibly; an HTML error page gets summarised into nonsense.

Also cap the tool’s timeout at something short — five seconds is plenty for a lookup. A hung request blocks the whole conversation turn, and Dust’s UI just shows a spinner with no explanation.

For anything with side effects (issuing refunds, sending emails), do not expose a write endpoint as a tool until you have logged a few hundred read-only runs. Models call tools confidently and wrongly.

When is this overkill?

If the answer is always a document, skip tools entirely — more tool choices make retrieval worse because the model splits attention. If the data changes hourly and lives in one database, a simple internal search endpoint added as a data source is easier than a tool with a schema.

Teams usually know they need tools when they start writing instructions like “if the user mentions a tracking number, ignore the documents.” That conditional logic is a sign the prompt is doing a tool’s job.

Cost: each tool call adds a round trip and its output to context. An agent that calls three tools per question costs noticeably more per message than a pure-retrieval assistant. Watch usage once tools are on.

Quick Summary

  • Custom tools in Dust are JSON-schema functions; the model selects them per turn from name and description.
  • Use a strict parameter pattern on identifiers so the agent cannot pass prose to the endpoint.
  • Trim API responses to the fields the agent needs before the model ever sees them.
  • Return errors as structured JSON with 200, never an HTML error page.
  • Keep write actions out of tools until read-only usage is proven over hundreds of runs.
Tags: