Caller input
Validate it, and fail with the right error
A published tool is an API: every caller reads its input schema and acts on its errors. Refuse a bad value before the tool touches the site, and fail loudly whenever the run cannot return what the caller asked for. Never return results computed without a value the caller supplied, except an input that tailors the answer, which a read returns labeled with the value the site applied.
Apply each caller input the way the site applies it, and only that. Don't add your own constraints between inputs, filter them, or swap in a value the caller didn't give; a write follows the site's preselected substitute only when the caller's own task asks for whatever the site ends up with (writes skill). For example, a store and a delivery ZIP that the site sets separately are both applied as given, even when they're far apart.
Express in the input schema everything it can hold, so the host refuses a bad value before the script runs: each field's type, an enum of the site's full set of options when the options are fixed, a minimum and maximum for numbers, counts and lengths, a format such as a date-only
CalendarDateor a pattern for a code, and which fields are required.Check every rule the schema cannot hold before any site action, and throw
new errors.InvalidInput(message, { field })at once, starting "Caller input error:" and naming the field and the rule. Such rules include:- an end date on or after its start date, and a check-out after its check-in;
- a date the task rules out, such as a departure before today in its airport's time zone. A date is past when it is before today in the site's time zone; UTC's date can be a day ahead or behind. On a site with places in several time zones, use the place's zone, such as a restaurant's or a departure airport's, when the tool knows it before any site action, and otherwise refuse only a date that is past in every time zone, such as one before yesterday in UTC;
- a count below one, or above the site's own limits, such as a party size or quantity the site caps, found while building and stated in the message;
- inputs that exclude each other, such as a store and a ZIP code where the site takes one;
- at least one of a set the tool needs one of, such as a record's number or its name.
When the refusal is obvious, start the message with "Caller input error:" so the caller gets it at once. It is obvious when the input alone breaks a rule of the task, as above, checked before any site action. It is also obvious when the page itself refuses the value in its own words, which the message quotes, or when the site's own lookup of a record's own key, such as an order, ticket or item number, or the site's own link to that record, shows the site's not-found or empty result. It is also obvious when the form marks an upload required and the tool's input for that upload holds no file, checked before filling anything. Never use that start for a breakage, which goes to repair: a URL the tool built itself, a page whose layout or controls the tool no longer finds, or a lookup, slider or list that hadn't loaded. Nor when a suggestion list or picker offered nothing, or a write finds a day disabled without the page saying why. Prefer not starting a refusal of an ambiguous value with it (below).
Throw the error that matches what happened:
InvalidInput: the caller's value is wrong or the site does not offer it. It breaks a rule above, or is not among the options the page lists, such as a store missing from its picker. Passfield, andavailable, every option the page offers as selectable, exactly as shown, whenever the page lists them. An option taken from the caller's own account goes inavailableas{ label, accountSpecific: true, maskedLabel }, marked as a question's option is ("Declare, read, ask", step 3). When the page refuses the value with an error of its own, prefer passing asfieldthe input that error belongs to, matched by where the page puts it, such as the field or label it sits under, or the field whosearia-describedbypoints at it, even when its words don't name the field. An error that covers several inputs or none, such as a notice for the whole form, leavesfieldout. The caller corrects the input and runs again. A write follows the site's preselected substitute instead when the caller's own task asks for whatever the site ends up with (writes skill).InputNotApplied: the value is valid and the site offers it, but the page did not apply it after the tool's bounded retries. It ignored, reset or replaced the value, such as a filter, sort or date (on a write, a location or store too), and the read-back shows its own default or another value (core skill, "Configure, then read"). Thrownew errors.InputNotApplied(message, { field, requested, applied, step, siteMessage }):fieldthe input's name,requestedthe caller's value,appliedthe value the page kept as read back (left out when it shows none),stepthe tool's step that failed, such asset_locationorapply_sort, andsiteMessagethe page's own error when it showed one. The run then fails and returns nothing computed without the caller's value. A read, or a run that left the site untouched, may run again with the same request. On a write, check it before the first commit step: a write that may already have changed the site still ends as a possible change, never retried. Never let an answer to a question make a filter, sort, date or other value that narrows the results optional or lookup-only.errors.LocationNotAppliedis an older name for the same error; writeInputNotApplied. Not this error: a number on a stepped scale set to the nearest step inside the caller's bound and returned as applied, a filter group the page disables reported as not offered, a broader choice that covers the value, a search query the site corrected or rewrote, returned withapplied_queryandquery_corrected(core and search skills), or a value a write typed that the site rewrote before any save, kept and reported as the writes skill says. Nor is a value a write's save kept differently that its output lists insaved_differences: free text before the final commit, and any value after it.- An input that tailors the answer, such as a location, store or vehicle, that the site still won't apply, or a location it says it does not serve, on a read: not an error (core skill, the input schema, "Inputs that tailor the answer").
- An option the page lists but greys out, such as a booked date or a sold-out size: not an
error on a read,
InvalidInputwithavailableon a write (core skill, "Configure, then read"); a write follows the site's preselected substitute only when the caller's own task asks for whatever the site ends up with (writes skill). - A read whose site says no to the whole request, such as a product it no longer sells,
prefers returning that no as a declared refusal with
site_messageover throwing (writes skill). - A write that declines the task because the caller's own limit or the page's state rules it
out, such as a total over the caller's price limit or a product number whose page names
another item than the caller's:
InvalidInput, thrown before the mark of the commit it guards (writes skill). Passfield, the input the caller would change,kind, the reason as a stable lowercase token such asover_price_limitoritem_mismatch, andavailablewhere the page lists choices, and give in the message the values the caller needs, such as the total the page shows beside the limit. That is a refusal: the run reports why, and that it changed nothing unless an earlier marked step ran, and the caller can run again with corrected input. It differs from a failure, a tool that broke, and from a write that may have changed the site and could not confirm it (both below). A write returns a refusal as its output only when its output schema declares that refusal, and only where the writes skill says one completes the run, such as before its first mark: any other output a write returns withoutverified()reports a possible change. - A read whose search for the caller's name or place opens one record whose name or place
differs from the caller's value: prefer
InvalidInput, withfieldthat input andavailablethat record as the input takes it, overInputNotApplied, which is for a valid value the page didn't apply. Don't return that record's data as the caller's answer. - When the site itself says no to a valid request, such as an item out of stock or a variant it does not offer, prefer the writes skill's refusal quoting the site.
- A write whose steps may have changed the site and then failed or could not confirm the
change: let it end as a possible change, which is never retried. Never throw
InvalidInputorInputNotAppliedto make it look untouched (writes skill). - A control the tool could not find, open or read, or a page that changed:
OperationFailure, neverInvalidInputorInputNotApplied. - Prefer a fast refusal for an item the site has no record of. A tool that takes an item's
id, key or URL, such as a product, listing, stock or order number, treats the site's own
not-found or no-results page for that value as
InvalidInput, withfieldthat input and the site's words quoted in the message, before any commit mark. It never throws another error for that page and never waits out a timeout for controls the page won't show. This holds for signed-in tools and writes too.
Never pick another value for the caller, such as a near match, the page's default or the first option, except a value that matches several site entries equally, where the tool may take the first and return the one it used, or a read's looser match, returning the option it used (core skill), and never report a refused or unapplied value in the output instead of throwing, such as a
sort_applied: falseflag or a "best-effort" or "lookup-only" description. The cases above that return results with what applied, and a declared refusal, are the only exceptions.
Ask the caller during a run
Try first. Ask only for what the page or the caller uniquely knows at that point:
- a choice whose options exist only once the run reaches them: the open seats of the flight the caller just chose, the delivery slots for the cart the run just filled, or which of the account's saved travelers, addresses or payment methods to use;
- whether to take a paid add-on within the tool's purpose that the page shows on the way to a commit when the input leaves it open, asked before the commit mark; a paid upsell outside the tool's purpose is declined, never asked (writes skill);
- which of several site entries the caller's value matches equally, such as a restaurant with several locations or a city with several airports, with those entries as the options, each selecting exactly one, when the tool asks instead of taking the first in the site's order; each tool decides which (core skill). That is ambiguous, as is a near-miss name the site offers alternatives for: prefer not starting a refusal of either with "Caller input error:" (above). A day or option the page greys out, with or without a reason, is not ambiguous and never a question (core skill, "Configure, then read");
- a code that is not part of signing in (auth skill): another code the site sends to confirm a protected action after sign-in, or a code the site sends during a write, signed out too (writes skill), such as a confirmation code by text or email;
- a fact only the caller has that the site now asks for.
Never ask for a value the request, the input or an earlier answer already supplied, a private
one included: use that value. Never undo an answer that declined something by doing it anyway
or by offering it as an input (core skill), except a costly choice a write still meets on its
path, which stays an input or a declared question (writes skill). In the tool, take it from its input, or a private one, such as
part of an identity number, through a declared secret question, never a plain-text field.
When question review finds a question redundant, remove the ask and use the supplied value; a
reworded question still asks for it again. A placeholder that stands in for a redacted value,
such as "[redacted value]", supplies nothing. A supplied value the site rejects, or two that
conflict, can still need a question, one that names the actual problem.
Work the request already covers proceeds without a question, such as finding the right field
or choosing among alternatives the request already allows. A supplied value the site does not
offer, whether the page does not list it or greys it out, is not such a question either, and
never one to ask about: it follows .agents/core/SKILL.md ("Configure, then read"), which never
substitutes another value; a write follows the site's preselected substitute only when the
caller's own task asks for whatever the site ends up with (writes skill). Asking the
owner to revise it or stop is the minter's own request_input question while it builds, as
AGENTS.md says.
Use a published input instead whenever the value is stable and the caller can supply it up front, such as a flight number, a date or a quantity. Never ask for a password, a username or any other login: the host asks for a login itself and signs in. Never ask for something the page shows, for permission to proceed with the operation the caller already asked for, or to solve a CAPTCHA.
Declare, read, ask
Declare every question the run may ask in the contract,
defineOperation({ name, input, output, questions }, ...), by id, with itstypeand a shortprompt. The publication review reads these declarations once, so the prompt names the choice or value, never a private value. Writequestionsas a plain literal inside the entrypoint's owndefineOperationcall: during the build the host reads it from that source, not from the running script, and a computed or imported declaration declares nothing, so every question is refused asUndeclared. Each question the example asks is also reviewed before the build's owner sees it. An id starts with a lowercase letter and holds only lowercase letters, digits and underscores, up to 64 characters (page_title, notpageTitle); the host refuses an invalid id before the script runs, and eachaskuses the declared id exactly.{ type: "choice", prompt, allowOther? }: one option;allowOtherlets the caller type their own answer, returned as{ other }(a build'srequest_inputalways allows it,AGENTS.md). Own text that repeats exactly one offered option's label (or its listed form entry,id (label)) returns that option.{ type: "multi_choice", prompt, minSelections?, maxSelections? }: several options, at least one unlessminSelectionssays otherwise, at most the options offered.{ type: "text", prompt, maxLength? }: free text.{ type: "confirm", prompt, followUp? }: yes or no, returned as{ confirmed }.{ type: "secret", secretKind, prompt, maxLength? }: a code the site sent that is not part of signing in, to confirm an action after sign-in or during a write, signed out too (one_time_code; a code that is part of signing in is acodefield of theauthenticatestep, never a question), an authenticator code (totp, which a saved login's TOTP fills without asking) or other private text (private_text). It stays out of traces, logs and the minting model. A secret you ask during the build withrequest_inputcomes back to you as a handle such as{{secret.s1}}, which the host fills in only when your explore, test oractsource runs live, and only where it is the whole string passed tofill,typeorpressSequentiallyor a field of a request to this site (core skill); the published script never holds a handle and asks for the value withaskinstead. Prefer asecretquestion of kindprivate_textfor an access code, such as a gate, door, alarm or lockbox code.- When the host says it fills the card from a payment method, never ask for card
parts: call
fillCard({ fields: [{ selector, slot }], total })with each card field's own CSS selector, matching one editable field across the page's frames, even inside the payment processor's frame, its slot (card_number,card_expiry,card_cvc) and the order total the checkout shows as{ amount, currency }. On a checkout the site opened in a pop-up, also passpopup: { opener: "primary", origin }as a sign-in step names it. The host fills the card and clicks nothing, so submit the payment in a later call under the write's commit rules. Fill the card last: settle and read back everything else the order needs first, then fill the card and press pay in the next step, with no step or question between them unless the checkout itself requires one, since the filled card lasts only minutes and a step that leaves or reloads the checkout can clear it. Wherever source callsfillCard, no source reads a field's value or the page's markup, runs or plants code in the page, opens a DevTools session, takes an accessibility snapshot, screenshot or PDF of the page, records the page, or reads a request body, except in an explore step before the card is filled, so delete such probes before any other step. A ZIP or postal-code field in the card form is slotbilling_postal_code, named in the same call as the card's other fields: the host fills it from the payer's billing address.
For a choice, read the options in the execute call that reaches it and return them as plain JSON. Each option has a
valuethe script acts on and alabelthe caller reads. Values are unique within a question. Offer only options the page will accept: skip taken seats, disabled slots and sold-out items. The value never leaves the run; the caller sees only the label. Mark an option that stops the write withdeclines: true. Picking it is the caller's no, as a confirm's no is.Mark an option taken from the caller's own account (a saved traveler, address, card or account) with
accountSpecific: trueand amaskedLabelthat keeps it recognizable without its numbers or email: a card's brand and last four digits, an address's saved label name without its recipient, street, city or ZIP, or a numbered placeholder for an address with no label name. The API and MCP show the masked label with a notice; only the owner's protected page shows the full label. A masked label that still shows five or more digits or an email address is replaced by the label's last four digits or a numbered placeholder. Prefer taking the saved entry the caller can name as an optional input, matching each entry whose full label contains it as whole words or whose masked label it is, and ask only when the input is empty or matches no entry or several, offering only the matches when several match. A purchase's final confirm, a choice or a confirm, also passesorderwith the checkout'scurrency, itsitems(eachname,quantity,unitfor an item sold by weight or measure, andpriceeach,lineTotalor both),fees(eachnameandamount),discount,shipping,tax,tipandtotal, amounts as decimal text, which everyone sees unmasked, so never the address or card.Ask once for everything the step needs, between two execute calls:
await ask("code")returns that question's answer;await ask(["seat", "note"])returns one answer per id;await ask({ seat: { options: seats }, code: {} })passes a choice's options, and nothing for the other types.
With an array or an object,
askreturns one answer per question id, so readanswer.<id>, as inanswer.seat. For one question,askOne("seat", { options })returns that answer directly. One ask takes up to eight questions, with up to 50 options per choice. A choice returns the chosenvalue, a multi-choice an array of values. Write answers into the next call's code withJSON.stringify.
The run waits with its browser open and its active budget stopped, and the next call
starts on the same page. Continue from there. Do not reload, search again or repeat an
earlier step, and never resubmit anything the run already submitted. A second click on a
marked step is not a resubmission when blockingRequiredFields returned the fields you
asked for and you called notCommitted for that step before asking: fill the answers, check
the step again, then call enteringCommit again for that step, and click once, as the writes
skill says. The wait can be long, so in that next call confirm the page still shows the chosen
option before acting on it.
Hand the browser to a person
A run can stop at one step, hand its live browser to a person, and go on once they mark the step done. The person sees the page and your prompt, and may review it, correct fields or do the step themselves, submitting included.
- Add a hand-off only when the build's request asks for a person to review or do a step, such as "let me check the form before it's submitted" or "I'll enter the signature myself". Never add one on your own. Never use one to get past a CAPTCHA or a bot check. Never use one to sign in, unless the request asks for a person to sign in.
- Declare it in
questionslike any other question, named for its context, such asreview_claim:{ type: "browser_handoff", prompt, show_inputs }. Writepromptas the task the person does, naming what to check: "Check the claim form: the policy number, the amount and the description. Correct anything that is wrong, then mark this step done." List inshow_inputsthe inputs that help the person check, by their top-level names, up to 20. Never list a secret or a file. - When the request wants the check optional per run, add a boolean input named for the
context, such as
review_claim_before_submit, with the default the request gives, and hand off only when it is true. Never a generic name such asreview_before_submit. When the request wants the check every time, add no input. - Fill the form first, then call
await handOff("review_claim"). It resolves once the person marks the step done, and asks nothing else in the same request. The deadline pauses meanwhile, up to 30 minutes. - In a write, the person may submit, so every declared commit step not yet confirmed reads
sent once the hand-off opens. After it, read the page again and handle both outcomes:
- The person submitted: read the site's confirmation, call
verified()and return the result. - The form still waits: check it is the same form, such as by its id, with no confirmation.
Call
notCommitted(name)for the step, then enter it withenteringCommitand submit, as usual. The form keeps the person's corrections.notCommittedworks once per step in a run, so a step you already put back before the hand-off can't go back again: a second call throwsCommitAlreadySent. Hand off before the step's first click. - Anything else, neither the same form nor a result you can read: throw
new errors.HandoffStateChanged(). The run stops without acting further and reportshandoff_state_changed, with a possible change to the site for a write.
- The person submitted: read the site's confirmation, call
references/browser-handoff.ts fills an example claims form, hands it to a person for review
when its input asks, then returns the person's submission or submits the form itself.
When no answer comes
ask throws ScriptInputFailure:
NoResponse: the caller did not answer within the request's window (at most 30 minutes for a hand-off and ten minutes for any other question, less when the job's window ends sooner). The run fails asno_response. It is never retried or repaired, and its result says whether a step before the question may already have changed the site.Unavailable: the host could not put the question to the caller, or the answer did not fit the question. A host that cannot show its browser to a person refuses a hand-off this way.Unauthorized: the caller's access to the job was revoked while the run waited.UndeclaredorInvalidOptions: the ask names an id thatquestionsdoes not declare, gives a choice no options or duplicate values, gives options to another type, or offers fewer options than the selection bounds need.
Let these failures end the run. Never catch one to pick a default, the first option or a guessed value. For a write, ask every question you can before its first commit step, reading options in a step that saves nothing, so an unanswered question leaves the site unchanged rather than holding a partial save. A question whose options the site shows only past a saved step, such as delivery slots for a cart that step filled, may come after it. A hold or a cart the run made before the question is reported as a possible change when no answer comes.
During a mint
A read build's example run, or a write build's act step, asks the build's owner
through the same request, and the answer comes back to the running script. Ask the owner each
decision once per build: one a declared question will ask during the run needs no
request_input of your own first. The host reuses an earlier answer to a choice,
multi_choice, text or confirm question, never a secret, code or login, for a later ask with the
same id, type, prompt and options, so keep a declared question unchanged between runs unless its
review asks for a rewording. Guardian
reviews each question first. When it asks for a rewording, nobody is asked, the ask
fails and the execution's result carries scriptQuestion with Guardian's rationale:
change the declared question as it says and execute again. If the owner does not answer
in time, the result carries scriptQuestion unanswered and the build goes on: decide
how to continue without the answer, as when your own request_input returns
no_answer. A write step that sent something before its question is reported as a
possible change; verify the site's current state before any further write. In a write
repair, or once the build is signed in or holds a login, an unanswered question still
ends the build as no_response. A read repair may still get unanswered or no_answer
while signed in: go on as above. Do not turn an
account-specific choice into a published input to work around a question; a value the
caller can type, such as a member number, is a free-form input instead.
references/caller-choice.ts books a seat on the caller's chosen flight: it asks for a
seat and a saved traveler once the flight's seat map is shown, then books once and calls
verified() after reading the confirmation back.
references/caller-code.ts asks for the code the site sends to confirm an address
change and enters it on the same page.