Writing prompts that succeed

A prompt is the instruction for one run on a user's account. How you phrase it decides whether the run completes.

The shape of a good prompt

Say three things:

1. Where. The area of the site, if it isn't obvious: "In Sent mail", "On the Orders page".
2. What. One task, with the specific item named: "the three newest emails", "invoice 4821".
3. What done looks like. The result you want back, or the exact effect you want.

A vague prompt and a clear one for the same task:

Check my email.

Summarize my three newest emails from the inbox: for each, give the sender, the subject, and one sentence on
what it asks me to do.

The first leaves the agent to guess what "check" means and when it's done. The second names the place, the count, and the shape of the answer, so the run knows when it's finished and WOOL knows what to confirm.

One task per run

For example, in a connected email account, split "Find the newest message from Dana and reply to it" into two runs. First find the message and return its sender, subject, and timestamp. Then use those details to identify the message in a run with the exact reply to send. You can inspect the first result before sending the reply. If the reply run fails, check its evidence before deciding whether to retry it.

Narrow with start_url

start_url tells the run where to begin, as a path or URL on the connected website. For an account on a shopping site with an Orders page, a request could look like this:

{ "prompt": "List the orders shown here with their totals.", "start_url": "/orders?status=open" }

Starting on the right page saves the run the work of finding it. It's the first thing to try when a run fails with no_progress or budget_exhausted. A URL off the connected origin returns 400 INVALID_START_URL.

Ask for data with a schema

If your code needs fields, pass an output_schema and read result.extracted instead of parsing prose. The run then knows which values to find, and it fails if a required value can't be backed by the page. Structured results has the rules.

Prompts with side effects

A side effect is a change the run makes on the website, such as sending a message or deleting a record. Name the exact change you want. For a connected email account, a reply prompt could be:

Reply to the newest email from Dana with: "Confirmed for Thursday at 10." Send it and stop.

Avoid conditions ("if it looks urgent, also…") and open-ended instructions ("handle my inbox"), which give the run room to do more than you meant. result.evidence.side_effects shows the action and what the page showed afterwards, so read it before anything else depends on the run.

What a prompt can't do

• Signing in, or anything on a site the user didn't connect, fails with session_expired or blocked_policy.
• CAPTCHAs and other human checks fail with needs_user.
• Data the page doesn't show fails with not_possible or unverified rather than an invented answer.

Design your product around those reasons instead of trying to prompt through them.

Next steps

Try a prompt in the playground and read its evidence, then wire up Handling failures.