Writing Instructions

Every workflow starts with one message from you. How you phrase it shapes how the agent routes it, how much it retrieves, and how much it actually does. This page covers patterns that work — and a few that waste credits or produce surprising results.

How instructions get classified

The FrontDesk agent reads your instruction and routes it to one of three paths:

  • Direct answer — your question is answerable from the current mindmap. No retrieval runs. The agent replies in text.
  • Simple edit — your instruction is purely structural or stylistic. The Editor applies the change; no Researcher involvement.
  • Research-intensive — your instruction requires new claims from the KB. The full Researcher → Editor → RePlanner loop kicks off.

You can't override the classification directly, but you can phrase your instruction to push toward the path you want.

Verbs that shape routing

A rough mental model of which verbs FrontDesk usually maps to which path:

Direct answer

  • "Summarize what we have on…"
  • "What does this branch say about…?"
  • "Compare these two nodes in plain text."

Simple edit (no retrieval)

  • "Rename this node…"
  • "Move these children under…"
  • "Group these as siblings of…"
  • "Polish the prose on this subtree."
  • "Fix the typo in…"

Research-intensive

  • "Expand…"
  • "Add evidence for…"
  • "Find counter-arguments to…"
  • "Build out…"

If you want a structural change without triggering retrieval, avoid "research verbs" like expand or add evidence. "Rename and regroup" is unambiguous; "expand the structure" is not.

Useful patterns

Be specific about scope

Vague: "Expand the section on Sea Peoples."

Better: "Expand the Sea Peoples subtree with the main counter-arguments from the last 20 years of scholarship, with citations."

The agent is happier with specifics. Where to retrieve, what to look for, how much depth — the more of these you provide, the less the RePlanner has to guess between iterations.

Batch tasks in one instruction

The agent processes all retrieval tasks in a workflow together. Three separate "expand this" messages cost three separate workflows; one message asking for all three runs once.

Vague (three separate workflows): "Expand Sea Peoples" → "Expand climate causes" → "Expand systems collapse"

Better (one workflow): "Expand the Sea Peoples, climate causes, and systems collapse subtrees. Treat each independently — don't merge or cross-link unless the evidence directly supports it."

Tell it what not to do

Constraints are as useful as goals. Common ones worth specifying:

  • "Don't create new top-level nodes."
  • "Don't restructure — only add content to existing nodes."
  • "Don't fabricate. If the KB doesn't have evidence, flag the gap."
  • "Use only sources I've labeled as primary."

Ask for the form, not just the topic

"Find evidence on X" gives you a list of citations.

"Find evidence on X. Create a sibling node per major position, with the supporting citations as children of each sibling" gives you a structure.

The agent will respect specific structural requests when you state them.

Reference selection when relevant

If you have nodes selected, you don't need to repeat what they are. "Expand the selected node" or "For each child of the selected node…" works fine. See Agent Context for what selection actually does.

Patterns that waste effort

  • "Just do whatever makes sense." Vague instructions trigger broader retrieval, which costs more credits and produces drifting results.
  • Stacking unrelated tasks in one instruction when you really want them treated as separate workflows. The agent will batch them together, which is the wrong move for genuinely independent jobs.
  • Repeating an instruction that just ran. If the result wasn't what you wanted, refine — don't re-issue. "That's too broad. Narrow to the post-2014 literature" is much more efficient than running the same instruction again.

Iterating on a result

You'll often want a follow-up. Some good follow-up phrasings:

  • "Refine the previous output: drop the climate-related claims, keep the rest."
  • "The Sea Peoples expansion was too speculative — re-run with stricter confidence requirements."
  • "Add citations to the new claims. Don't change the text."

The agent reads the conversation history, so you can reference "the previous output" or "that section" directly — it knows what you mean.

What's next