Plori

Official

by plori-ai

Overview Schema Source Related Servers Discussions Admin

JavaScript

Remote

Submit worker changes for review

submit_workspace_changeset

DestructiveIdempotent

Send a worker's saved files as a changeset for review when its run ended in error, was cancelled/stopped, or needs recompare; Plori compares them with the Workspace's current files.

Instructions

Submit a worker's saved files for review as a changeset: Plori compares them with the Workspace's current files. Plori submits a worker's saved files itself when its run completes normally and they change at least one file, and accepts a clean comparison; use this tool for a worker whose change_status is still unsubmitted after its run ended in error, was cancelled or was stopped, or after phase recompare_required. Submitting a worker that Plori submitted returns that changeset. The worker must have save_state ready (get_workspace_worker); otherwise the call is refused with 409 workspace_worker_not_saved. The Workspace's files do not change. The comparison runs after the call returns: poll get_workspace_changeset until compared is true, then accept_workspace_changeset accepts a changeset in phase review_ready and reject_workspace_changeset rejects one. Submitting the same worker again while the Workspace's current revision is unchanged returns the same changeset; after the current revision changes, for example because another changeset was accepted, it creates a new changeset compared with the new current revision.

Input Schema

Name	Required	Description	Default
`workspace_id`	Yes	The Workspace UUID.
`worker_request_id`	Yes	The worker whose saved files to submit (worker_request_id).

Output Schema

Name	Required	Description
`phase`	Yes	The step the changeset is in: checkpointing, creating_integration and comparing while the comparison runs; review_ready when accept_workspace_changeset can accept it; needs_resolution when it has conflicts; saving_result after accept until result_revision is set; recompare_required when the Workspace changed after the comparison (submit the worker again); then accepted, rejected or failed.
`state`	Yes	submitted (being compared, or ready for review when phase is review_ready), conflicted (the worker and the Workspace changed the same paths; see accept_workspace_changeset for recovery), accepted, rejected or failed.
`changes`	No	The changed paths, at most 500. get_workspace_changeset returns them; list_workspace_changesets leaves them out.
`compared`	Yes	True when the comparison is complete and changes and conflicts are known.
`conflicts`	No	The paths that conflict, when state is conflicted.
`no_change`	No	True when the worker changed no files.
`created_at`	Yes	When the changeset was submitted.
`updated_at`	Yes	When the changeset last changed.
`auto_accept`	No	Set only for a changeset whose comparison was clean and changed files: pending (the platform may still accept it), accepted (the platform accepted it) or abandoned (the platform stopped and will not accept it).
`change_count`	Yes	The number of changed paths.
`changeset_id`	Yes	The changeset UUID.
`workspace_id`	Yes	The Workspace UUID.
`base_revision`	Yes	The revision the worker's copy started from.
`result_revision`	No	The new current revision of the Workspace once an accepted changeset is saved.
`terminal_reason`	No	Why a failed changeset failed.
`working_copy_id`	Yes	The worker's copy that the changes come from.
`changes_truncated`	No	True when there are more than 500 changed paths.
`incoming_revision`	Yes	The worker's saved revision. read_workspace_file reads its files.
`validation_evidence`	No	The evidence given when the changeset was accepted.
`comparison_current_revision`	No	The Workspace revision the changes were compared with. accept_workspace_changeset takes it as expected_current_revision.

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.17.1Oct 18, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=true) it discloses the save_state ready precondition and the exact refusal code 409 workspace_worker_not_saved, the asynchronous comparison that runs after the call returns, and the state of the Workspace's own files. It also refines idempotency beyond the flat hint: resubmission against an unchanged revision returns the same changeset, but a changed current revision produces a new one. The statement that Workspace files do not change sits alongside destructiveHint=true without directly contradicting it, since a changeset object is created.

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?

Front-loads the core action and then layers preconditions, error behavior, and lifecycle in a logical order; nothing is irrelevant. It is dense and long-winded in places (the auto-submission digression and the final revision-explainer), but the length is defensible for an async, stateful operation.

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

Completeness5/5

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

With an output schema present, the description needn't document return values, and it still covers everything else an agent needs: when to call, when not to, the blocking precondition, the failure code, the post-call polling contract, and revision-sensitive idempotency. The full lifecycle from submit through accept/reject is traceable from this text.

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% and both parameters are documented in the schema, so the baseline is 3. The description contextualizes worker_request_id via get_workspace_worker and the save_state requirement, but adds no format or syntax detail beyond the schema.

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?

Specific verb + resource + artifact: it submits a worker's saved files for review as a changeset and explicitly contrasts this with Plori's own automatic submission, so an agent can separate it from get_workspace_changeset/list_workspace_changesets. The scope statement ('compares them with the Workspace's current files') pins down exactly what the operation produces.

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

Usage Guidelines5/5

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

Gives an explicit when-to-use condition: only for a worker whose change_status is still unsubmitted after a run ended in error, was cancelled, was stopped, or after phase recompare_required. It also states the normal-run path where Plori submits on its own, which is the key exclude condition, and names the follow-up tools (poll get_workspace_changeset, then accept/reject).

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