Prompting tips.

You don't need to be a prompt engineer to get good answers from Orchid's agents. A few small habits go a long way.

State the outcome, not the steps

Agents plan well when they know where you're going. Lead with the outcome and let them figure out the path.

  • Good: "Chart weekly revenue by channel for the last 90 days."
  • Worse: "Write a SQL query that joins orders and channels then aggregates by week then makes a chart."

The second form ties the agent's hands. The first lets it pick the right table, the right grain, and the right chart type.

Anchor to your project

Reference cells, dashboards, or files by name. The agent reads the project before planning, but explicit anchors save a turn.

  • "In cell q1, swap the metric from sum to median."
  • "Use the connection named warehouse."
  • "Pin the result to the Q1 review dashboard."
A chat turn referencing a specific cell id, with the cell highlighted in the notebook./docs-images/agents/anchor.png
Mentioning a cell by id is the fastest way to point at it.

One outcome per turn

Long multi-step asks become long multi-step plans that are hard to review. Break them up. Ask for the data first, then the chart, then the writeup. You'll spot mistakes earlier and re-do less work.

Tip

When you do need a multi-step request (e.g. for a one-shot dashboard build), switch to multi-agent mode. The orchestrator splits the work and labels each phase, which makes review easier.

Show, don't describe

If your output schema is non-obvious, paste a couple of example rows or a target shape. Agents reproduce examples reliably; they guess less reliably.

Match this shape, one row per cohort:

cohort_month | week | retained_pct
2026-01-01   | 0    | 100.0
2026-01-01   | 1    | 62.3
2026-01-01   | 2    | 47.8
...

Iterate in chat, not by re-prompting

When a proposal is almost right, don't reject and re-ask the whole question. Reply with the change — "swap to a stacked bar", "add a 7-day average overlay", "filter to the last 30 days." The agent edits the proposal in place.

Use the model that fits the task

The free-tier Gemini model is great for SQL drafting, light analysis, chart selection. For longer-chain reasoning — debugging a flaky model, choosing between three statistical approaches, writing a polished executive summary — pull in Anthropic Claude or OpenAI GPT-4o via BYO key. The model picker is in the panel header.

Be explicit about destructive intent

Agents err on the side of read-only. If you genuinely want them to write to the database — "delete the test rows", "update the orders.status column" — say so and lift the write lock on the connection first. The approval prompt still appears, but the agent won't hedge for ten turns before proposing the change.

Warning

Even a clear write request gets per-statement approval. Lift the connection lock when you start; lock it back down when you're done. See Approvals for the full model.

Cheat sheet

  • Lead with the outcome.
  • Anchor with cell ids or connection names.
  • One outcome per turn.
  • Paste example rows when the shape matters.
  • Iterate by replying, not by restarting.
  • Match model to task.
  • Be explicit when you want writes.

Back to Agents overview, or jump to Single agent, Multi-agent, Tools, or Approvals.