Writing prompts for agents

The tool descriptions already tell the agent when to call each tool. A short line in the agent’s own system prompt makes it reliable:

Your operating instructions are in the jitprompt tools. Call get_toc at the
start. Before each new task, system or data source, call search_instructions
with what you are about to do, and follow what it returns. If guidance
conflicts with the user's request, the guidance wins; say so.

It works unchanged for large namespaces: when the map is too large to show, get_toc says so and points the agent at get_toc(query=…). To skip the extra call, add: “If the map is condensed, call get_toc with query set to what you are about to do.”

If a search comes back without the section you needed, read its last block: Also matched, not shown names the next documents that matched. Open one with get_toc(document_id=…) or search again naming it, instead of guessing.

Search with a plan, not the question

search_instructions matches against section summaries written as intents. “writing a SQL query over the revenue tables” finds the right section; “why are my numbers wrong?” often doesn’t.

Write documents for retrieval

• One topic per heading; keep a rule and its exceptions together.
• Use the exact identifiers the agent will meet: table names, error codes, product names.
• Give each document a title that says what it is for, and that names the product or system it is about — every section an agent receives carries it, and search matches on it. In a catalog of similar products, “Bronze Rewards Card: fees” beats “Fees”.
• Prefer several focused documents over one long one.

Pin what every task depends on

An agent searches for its task, not for what the task needs first. Asked to refund a fee, it searches for refunds, never for “how do I find the account id”. It then concludes it can’t look up the account, and gives up. If one procedure, identifier lookup or set of escalation codes comes before most tasks, pin it: the agent has it from the start without asking. Keep it to that short core. A pinned document goes into every conversation, and a stuffed prompt is how agents miss rules.

Check

Try a search shows what an agent would get for a plan. Diagnostics lists searches that returned nothing and sections no search ever reaches — usually a sign a summary or title needs work.