Plori

Official

by plori-ai

Overview Schema Source Related Servers Discussions Admin

JavaScript

Remote

Get Workspace worker

get_workspace_worker

Read-only

Check a Plori workspace worker's run, save, and change status by workspace and worker request ID to see if files were saved and changes accepted.

Instructions

Get one worker's status: whether it has started (run_id), how its run ended (run_status), whether its files are saved (save_state ready with saved_revision_id) and whether its changes were submitted and accepted (changeset_id, change_status; Plori submits the saved files of a normally completed run itself). A completed run alone does not mean the files are saved or in the Workspace; check save_state and change_status. get_run_result with run_id and workspace_id reads the worker's reply and its approval requests. No run starts and nothing changes.

Input Schema

Name	Required	Description	Default
`workspace_id`	Yes	The Workspace UUID.
`worker_request_id`	Yes	The worker_request_id that create_workspace_worker returned.

Output Schema

Name	Required	Description
`cause`	No	Machine-readable cause of a run that did not finish normally.
`run_id`	No	The worker's run, present once it has started. get_run_result reads its reply, steer_workspace_worker sends it a message while it runs, and cancel_run stops it.
`status`	Yes	Where the worker is: received, ready or blocked while it waits to start (queue_reason says why it is blocked), starting, running, or terminal when its run has ended (run_status says how).
`activity`	No	The worker's expiring activity hint; absent when expired or unavailable. The saved changeset is authoritative.
`agent_id`	Yes	The agent that runs the worker. get_run_result and cancel_run take it with run_id.
`run_status`	No	The run's status: running, awaiting_input (paused on an approval or question; get_run_result lists them), completed, error or cancelled.
`save_state`	Yes	Whether the worker's files are saved: none (no run has ended), pending (saving), ready (saved as saved_revision_id), failed (see save_failure) or unconfirmed (the save could not be confirmed).
`session_id`	Yes	The worker's own conversation id. It is private to the worker; send_workspace_message cannot select it.
`stop_reason`	No	The stop reason of an ended run, when one was recorded.
`changeset_id`	No	The changeset submitted for this worker's files, if any.
`queue_reason`	No	Why a waiting worker has not started, such as a capacity or balance limit.
`save_failure`	No	Why the save failed, when save_state is failed.
`workspace_id`	Yes	The Workspace UUID.
`base_revision`	Yes	The saved revision the worker's copy started from.
`change_status`	Yes	unsubmitted until the worker's files are submitted (by Plori when the run completes normally with changed files, or by submit_workspace_changeset), then the changeset's state.
`task_group_id`	Yes	The task group of the worker. get_workspace_costs and stop_workspace_task_group take it.
`working_copy_id`	Yes	The copy of the Workspace files that this worker edits. The Workspace's current files do not change until its changes are accepted.
`saved_revision_id`	No	The saved revision that holds the worker's files once save_state is ready. read_workspace_file reads files from it.
`worker_request_id`	Yes	The worker's id; get_workspace_worker takes it.
`saved_operation_id`	No	The save that produced saved_revision_id.

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.17.1Oct 18, 2026

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover read-only safety via readOnlyHint=true, and the description reinforces this with 'No run starts and nothing changes'. It adds genuinely useful lifecycle semantics beyond the annotations — that a completed run does not imply saved files or an accepted changeset, and that Plori auto-submits saved files of a normally completed run.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense but front-loaded: the core action leads, then state fields, then the caveat, then the alternative and the read-only guarantee. Every sentence carries information, though the run_id/save_state explanation is slightly repetitive.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values need not be explained, and the description still flags which fields matter for interpreting readiness. Annotations cover the safety profile. Only edge cases (e.g., invalid or unknown worker_request_id) are unaddressed, which is minor.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters (workspace_id, worker_request_id) are already documented, including the provenance note that worker_request_id comes from create_workspace_worker. The description repeats run_id/workspace_id in the get_run_result pointer but adds no new parameter-level detail.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Get one worker's status') and immediately enumerates the state dimensions returned (run_id, run_status, save_state, changeset_id, change_status), which lets an agent separate it from list_workspace_workers and get_workspace_changeset. The distinction from get_run_result is also named explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear selection rule: 'check save_state and change_status' because 'a completed run alone does not mean the files are saved'. It also routes the agent to get_run_result for the worker's reply and approvals. No explicit when-not-to-use case, but the sibling boundary is drawn well.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.