unlob Docs
Console
Browse documentation

Prompting an agent to use unlob well

The same three lines belong in almost every system prompt that holds these tools.

Every framework guide on this site repeats a version of the same three instructions in its example agent, because the same three model behaviours go wrong without them, regardless of which framework is calling the tools. This page collects the three in one place, with the specific failure each one prevents, rather than leaving them scattered one framework example at a time.

The three lines

1. Use assemble_context for open questions ("what should I know about X"), and
   web_search for specific ones ("find the page that says Y").
2. Before stating anything as established fact, call corroborate on the passage
   you are relying on and report how many independent sources carry it.
3. If a result has partial: true, part of the corpus was unreachable — say the
   answer is incomplete rather than reporting it as complete.

Nothing here is exotic — it is the same guidance Choosing a call gives in more depth, compressed to what fits in a system prompt.

Why each one is load-bearing

Line 1 exists because a model left to guess between search and assemble_context will default to whichever it reached for first in the conversation and keep using it, rather than switching per question. An agent that only ever calls search, even for “what should I know about the merger”, does the deduplication and ranking work itself, badly, inline in its answer, when a single assemble_context call would have done it correctly, for a fixed 3 credits however much it packs.

Line 2 exists because nothing about a plain result list distinguishes one independently reported fact from forty reprints of the same wire story — see Reading a result on independent_sources. A model is not being careless when it treats the two as equally strong evidence; it has no way to tell them apart without calling corroborate, so the instruction has to be explicit rather than assumed.

Line 3 exists because partial is a 200. Nothing about the HTTP status tells a model anything went wrong, and a short result list reads exactly like a genuinely small corpus unless something says otherwise. Left unsaid, “three results, partial: true” and “three results, complete” produce the identical answer — “there is not much on this” — when only one of them is actually true.

Where instructions should live versus where defaults should

Not everything belongs in the prompt. min_independent_sources and collapse=story are better set as defaults in the tool’s own code — as every framework guide on this site does — than left as prompt instructions the model has to remember and can talk itself out of under time pressure. The dividing line: a value the tool should never accept without is a default baked into the request; a judgement call about when to use which capability is a prompt instruction, because that genuinely depends on the question being asked and cannot be baked into one call’s parameters.

Bake into the toolPut in the prompt
min_independent_sources floorYes — a floor the model can raise, not lower—
collapse=storyYes, for anything touching news or syndicated content—
Which call to use—Yes — depends on the question
When to run corroborate—Yes — a judgement about what matters enough to check
How to phrase partial—Yes — the exact wording is a UX choice

A worked prompt

Combining the three lines with the framework-agnostic system prompt shown across this site’s guides:

You are a research assistant with access to unlob, a web search API.

Use assemble_context for open questions ("what should I know about X"), and
web_search for specific ones ("find the page that says Y"). Before stating
anything as established fact, call corroborate on the passage you are relying
on and report how many independent sources carry it. If a result has
partial: true, part of the corpus was unreachable — say the answer is
incomplete rather than reporting it as complete.

Cite the URL for every claim you make from a search result.

The citation line at the end is not one of the three — it is ordinary practice for any retrieval tool, unlob included — but it is worth keeping alongside them since a claim with no citation and a claim from an uncorroborated single source read identically to a user unless the agent is told to distinguish both.

What a prompt cannot fix

No instruction compensates for a tool definition that hides the information the model needs to follow it. If your integration strips independent_sources out of what the model sees — easy to do by accident when hand-shaping a tool’s return value — line 2 above has nothing to act on no matter how clearly it is worded. Check what the model actually receives before assuming a prompt fix will solve a behaviour that is really a missing field.

FAQ

Do I need all three lines for every agent? An agent that only ever does lookup — never synthesises, never asserts a fact as established — can drop lines 1 and 2 and keep line 3 alone, since partial handling matters for any use of search at all.

Does this replace framework-specific prompting advice? No — it is the unlob-specific layer underneath whatever prompting conventions your framework otherwise recommends. Each framework guide on this site shows it embedded in that framework’s own agent or instructions field.

Should the model see the raw partial field, or should my code translate it first? Either works; several framework guides on this site show the client-side code prepending a plain-language warning before the model ever sees the JSON, which is slightly more reliable than trusting the model to notice a boolean field on its own.

Bottom line

Three instructions cover the three places a model’s default behaviour diverges from what this API needs: which call to reach for, when to verify rather than assert, and how to read an incomplete result. Bake the numeric defaults into the tool; keep the judgement calls in the prompt.

Next