Pause for the user to confirm a recommended path or choose one.
Full description
Pause for the user to confirm a recommended path or choose one.
Use this once you have reasoned to the viable path(s) forward and
want the user to commit. Pass ONE option when the investigation
converges on a single recommended path — the scheduler is being
asked to accept it, not compare it against anything. Pass TWO OR
MORE only when there are genuinely different courses of action and
the choice is the scheduler's to make; do not split one path into
several options just to have something to compare, and do not
collapse real alternatives into a single option. Each option
carries a short title, a longer description, an optional impact
summary, and a structured plan (the actions you intend to take if
it is chosen).
Every option that would change any record carries ``steps`` (1-12
ordered ``{"title", "caption"?}`` entries describing what you will
do; these become the run's todo list once the user accepts) and a
``plan`` declaring each write (the move or allocation, the
dispatch, any message to a resource), however many options you
offer. The message to the customer or site contact is always a step
in ``steps`` but never a plan action: ``send_sms`` cannot be
pre-approved, so that step asks for approval with an editable draft
when the run reaches it. An accepted option without a plan makes
the scheduler approve every write again one by one. Only a
do-nothing option ("leave the slot open", "close as empty") may
omit them.
With ONE recommended option, also fill ``headline`` (one line,
≤120 chars, e.g. "Move JOB-0412 to tomorrow 09:00-11:00 with Tony
Russo"), ``why`` (a sentence explaining the reasoning, with every
named record written as ``[label](kind:id)`` so the inbox can
render it as a chip — kind one of resource|job|site|customer|contact|time.
No other kind is accepted: a record with no matching kind goes in
the text as a plain label with no link; plain prose needs no
refs) and ``confidence`` (low|medium|high). When the option moves a job to a
resource, also fill ``fit_proposal`` from the records you already
read: the job, the resource who would cover it, the resource losing
it if any, and the proposed slot. Never state hours, travel minutes,
capacity or a fit verdict anywhere in the option: the client works
those out from the tenant's own data and draws the picture.
The tool emits a structured payload the inbox renders as option
cards. When the user selects one, the run resumes and the tool
returns the selection. Selecting an option commits you to its
``plan``: carry out each declared action exactly as declared — the
same tool, the same arguments and no others — and it runs without
asking again. A call that adds, drops or changes an argument asks
again, so declare the full argument list it will run with. Run each
declared action with the tool it names; when that tool is not bound
to you, hand it off as your instructions describe, and the
acceptance carries across the hand-off. An option with no ``plan``
pre-approves nothing: once the scheduler picks it, propose that path
again as ONE option whose ``plan`` declares every write and resource
message it makes, before any write or message, so the scheduler
approves the whole change once instead of write by write. A step whose tool
cannot be pre-approved, such as a customer ``send_sms``, stays a
step and asks when it runs; a path left with only such steps needs
no new proposal.
A ``plan`` is limited to what the scheduler is being shown, and the
tool rejects the call otherwise:
* at most 36 actions;
* each ``name`` one of ``allocate_job``, ``cancel_job``,
``create_availability``,
``deallocate``, ``edit_recurring_schedule``, ``move_job_time``,
``move_shift``,
``reallocate_job``, ``reassign_shift``,
``shift_job_schedules``, ``unschedule_job``, ``update_job_schedule``,
``dispatch_resources``, ``notify_allocated_resources``,
``notify_job_cancellation`` or ``send_one_off_message``. Any
other action stays out of the plan and asks for approval when you
call it. ``send_sms`` and ``request_sms_confirmation`` are not on
that list: each sends to a bare phone number with a free-text
body rather than to a record, so an SMS sent either way always
asks, even when a step describes it. To pre-approve a message to
a worker, use ``send_one_off_message`` and name that
``resource_id``;
* each ``args`` a flat mapping of strings, numbers, booleans, nulls
or lists of those;
* each action declaring the record it acts on, as an ``*_id`` or
``*_ids`` arg. An action that names no record is refused;
* ``steps`` present: an option that declares a ``plan`` has to
show the scheduler the steps it will take;
* each action carrying a ``step`` (0-based index into ``steps``),
and that step spelling the action out. The step's own title or
caption must name every record the action acts on (its ``*_id``
/ ``*_ids`` values, either as the id itself or as the label an
``[label](kind:id)`` ref on this card resolves for that exact id)
and must say what the action does in a scheduler's words:
"cancel" for ``cancel_job``, "reassign", "reallocate" or "move"
for ``reallocate_job``, "text", "message" or "notify" for
``send_one_off_message``, and so on. A step that does not
describe the action does not pre-approve it. Correct — step 0
names the job the action acts on::
steps = [{"title": "Allocate JOB-6206 to Nicole Park"}]
plan = [{"name": "allocate_job",
"args": {"job_id": "0014...", "resource_ids": ["0034..."],
"status": "<an allowed status>"},
"step": 0}]
Wrong — step 0 never names the record the action binds, so the
call is refused even though the action itself is well-formed::
steps = [{"title": "Fill the morning gap"}]
plan = [{"name": "allocate_job",
"args": {"job_id": "0014...", "resource_ids": ["0034..."],
"status": "<an allowed status>"},
"step": 0}]
* each ``args`` using the named tool's own argument names exactly,
including every argument it requires — nothing renamed, nothing
dropped, nothing extra. The required argument names per
pre-approvable write tool are:
* ``allocate_job``: ``job_id``, ``resource_ids``, ``status``
* ``reallocate_job``: ``job_id``, ``new_resource_id``, ``allocation_status``
* ``deallocate``: ``resource_ids``, ``job_ids``
* ``update_job_schedule``: ``job_id``
* ``move_job_time``: ``job_id``, ``start_time``, ``end_time``
* ``shift_job_schedules``: ``job_ids``
* ``create_availability``: ``resource_id``, ``start``, ``finish``, ``is_available``
A status value the platform refuses is echoed back with its own
allowed list in the error, so do not memorize or guess status
values here;
* an option that carries a ``fit_proposal`` and declares any
``allocate_job`` also declaring a time write for the exact
``fit_proposal.job_id``, even if the allocation names another job.
``allocate_job`` creates the allocation and nothing else, so a
job waiting to be scheduled keeps the ``Start``/``End`` it
already had — the slot on the card only happens if the plan
declares ``move_job_time`` (or ``update_job_schedule`` when the
duration, address, location or region changes too) for the same
job, with that slot's start and end. Declaring a
``fit_proposal`` slot without one of those two actions for that
job is refused, e.g. an ``allocate_job`` action alone never moves
the job to the proposed slot.
Args:
summary: One-line framing the inbox renders above the option
cards (e.g. "No nearby resources can arrive on time. Here
are your best options:").
options: At least one option dict. Pass a JSON list (NOT a
JSON-encoded string). Shape::
{
"id": str,
"title": str,
"description": str,
"impact": str | None,
"plan": [{"name": str, "args": dict, "step": int,
"depends_on": [int, ...] | None}, ...] | None,
# ``args`` must use the named tool's exact argument names
# and include its required ones — see the per-tool
# argument lists above. ``depends_on`` lists the indexes
# of EARLIER actions in this plan that must succeed
# first, e.g. a deallocate that frees a resource before
# an allocate of another job to it; if one fails, this
# action is skipped.
"recommended": bool | None,
"headline": str | None,
"why": str | None,
"steps": [{"title": str, "caption": str | None}, ...] | None,
"confidence": "low" | "medium" | "high" | None,
"fit_proposal": {
"job_id": str, "covering_resource_id": str,
"vacated_resource_id": str | None,
"start": str, "end": str, "timezone": str | None,
} | None,
}
Correct call: ``propose_options(summary="...", options=[{"id": "a", ...}, {"id": "b", ...}])``
Wrong call: ``propose_options(summary="...", options="[{\"id\": \"a\", ...}]")``
Returns:
``{"selected_id": str, "feedback": str | None}``, plus a
``next_step`` instruction when the selected option declared no
``plan``. ``selected_id``
is one of the option ids supplied; ``feedback`` is optional free
text the user attached to the selection. When exactly one option
is supplied, it is normalised to carry ``recommended: True``
regardless of what was passed in — a lone option IS the
recommendation. If the ``summary`` or ``options`` payload fails
validation, a ``tool_error`` dict (``error``/``suggestion``/
``error_type``) is returned instead so the model can self-correct.
Raises:
ProposeOptionsError: If the resume payload from the client is
malformed or does not include a recognised option id — a
client-side contract violation, not something the model can fix.
Plan action argument names (`?` marks optional; declare every other arg with these exact names):
- allocate_job(job_id, resource_ids, status one of ['Pending Dispatch', 'Dispatched', 'Confirmed', 'En Route', 'Checked In', 'In Progress', 'Complete', 'Deleted', 'Declined'])
- cancel_job(job_id, abort_reason)
- create_availability(resource_id, start, finish, is_available, status? one of ['Pending', 'Approved', 'Declined'], type?, notes?)
- deallocate(resource_ids, job_ids, all_resources?)
- dispatch_resources(job_id, resource_ids)
- edit_recurring_schedule(job_id, new_start_time?, new_end_time?, new_duration?, unlock_recurring?)
- move_job_time(job_id, start_time, end_time)
- move_shift(shift_id, start_time, end_time)
- notify_allocated_resources(job_id, resource_ids)
- notify_job_cancellation(job_id)
- reallocate_job(job_id, new_resource_id, allocation_status one of ['Pending Dispatch', 'Confirmed', 'En Route', 'Checked In', 'In Progress', 'Complete', 'Deleted', 'Declined'])
- reassign_shift(shift_id, new_resource_id)
- send_one_off_message(resource_id, message, protocol, expects_reply?)
- shift_job_schedules(job_ids, days?, hours?, minutes?)
- unschedule_job(job_id)
- update_job_schedule(job_id, start?, end?, duration?, address?, location_id?, region_id?, geo_latitude?, geo_longitude?, locked?)