Tools

Elicitly’s tools fall into two groups. The elicitation tools — elicit_confirm and elicit_form, with elicit_doctor as the diagnostic — put a human in the loop from any prompt or Agent Skill, and ship in every edition. The approval tools — elicit_approval through elicit_result — drive the Pro Edition’s hosted Approval Flow.

Every tool returns its result as a JSON string (except elicit_ping, which returns plain text), and the shapes on these pages match the server handlers exactly.

Tool	Edition	What it does
elicit_approval	Pro	Record an approval request; best-effort URL-mode prompt
elicit_await	Pro	Bounded long-poll until a request is decided
elicit_confirm	Free	OK/Cancel confirmation, modeled on JavaScript’s confirm()
elicit_doctor	Free	Report the host’s client-feature support; optionally probe it live
elicit_form	Free	Fire a form elicitation with your own JSON schema
elicit_history	Pro	Retrieve an agent’s (or organization’s) elicitation history, jump-to-page
elicit_ping	Pro	Connectivity smoke test
elicit_proposal	Pro	Review, edit, and selectively approve a proposed record create-or-update as a diff grid
elicit_result	Pro	Fetch a resolved request’s decision and data (idempotent)
elicit_selection	Pro	Ask a human to pick from a list — disambiguation, choose one or many
elicit_status	Pro	Non-blocking status read for a request

Free tools ship in the local stdio server (@elicitly/local) and the hosted Pro server — Pro is a superset. Pro tools exist only on the hosted server and drive the Approval Flow.

Choosing a tool

Start from what you need the human to do:

You need the human to…	Reach for	Shape of the answer
Answer one yes/no question, right in the host	elicit_confirm	confirmed: true / false / null (three-state)
Fill in a few typed fields, right in the host	elicit_form	Raw { action, content } with your schema’s fields
Approve or reject something — durably, from any device	elicit_approval	decision (+ formSubmission in form mode) via elicit_result
Pick one or more options from a list you supply	elicit_selection	selectedIds via elicit_result
Review, edit, and selectively apply a record change	elicit_proposal	action + included-fields-only values via elicit_result

Two properties separate the rows:

• Where the human answers. The Free tools (elicit_confirm, elicit_form) render a dialog inside the connected host and resolve in a single call — but only when the host actually implements elicitation; run elicit_doctor to find out. The Pro tools return immediately with a hosted reviewUrl that works from any browser on any device, whoever the reviewer is, however long they take.
• How much structure the answer has. A bare yes/no (elicit_confirm / elicit_approval json mode), typed fields (elicit_form / elicit_approval form mode), a choice among your candidates (elicit_selection), or a field-by-field edit-and-include pass over a proposed record (elicit_proposal).

For a Pro request’s lifecycle after creation:

You need to…	Reach for
Block until it’s decided	elicit_await
Check status without blocking	elicit_status
Fetch the decided outcome (idempotent)	elicit_result
List past requests — yours or the organization’s	elicit_history
Prove the authenticated session round-trips	elicit_ping