Plori

Official

by plori-ai

Overview Schema Source Related Servers Discussions Admin

JavaScript

Remote

Create Workspace

create_workspace

DestructiveIdempotent

Create a cloud workspace with durable files, saved revisions, conversation history, and an agent that runs messages, optionally using an existing agent.

Instructions

Create a Workspace: durable files with saved revisions, a main conversation and run history. Unless default_manager_agent_id is given, the call also creates the Workspace's agent, which runs the messages sent to the Workspace; that agent counts against the account's agent limit, and the Workspace counts against its Workspace limit. default_manager_agent_id selects an existing agent instead. Every Workspace has an agent; an agent that receives no messages does no work and costs nothing. The call returns after the Workspace's first revision exists. No run starts. idempotency_key identifies the request for 24 hours: the same key with the same arguments returns the same Workspace, and the same key with different arguments is refused with 422 idempotency_key_reused. Names are not unique: a new key with a used name creates a second Workspace. Task messages, the files the agent reads, and the agent's work are sent through OpenRouter to these model providers: OpenAI, DeepSeek and Anthropic. All three supply the agent's models, with Anthropic for advisor reviews and OpenAI for result reviews. TypeSafe receives short typed-judgment requests about the agent's steps. Runs started through this connector do not generate video. The provider list follows Plori's model catalog and can change.

Input Schema

Name	Required	Description
`name`	Yes	A display name for the Workspace. Names are not unique and do not identify the Workspace.
`account`	No	Omit this field to create the Workspace in the caller's own account. To create it in an account that shares Workspaces with the caller, pass that account's account.user_id from list_workspaces, and only when the caller's role there is member; a viewer cannot create a Workspace in that account.
`idempotency_key`	Yes	A string of 1-255 bytes you generate for this creation. The same key with the same arguments returns the same Workspace for 24 hours.
`default_manager_agent_id`	No	The Workspace's agent, which runs messages sent to this Workspace: the UUID of an existing agent of the account. Omitted or empty, a new agent with the Workspace's name is created.

Output Schema

Name	Required	Description
`id`	Yes	The Workspace UUID.
`name`	Yes	The display name; not unique.
`role`	Yes	The caller's role: owner, member or viewer.
`state`	Yes	active, adopting (its files are moving to new storage; runs are refused until it is active again), deleting or deleted.
`account`	Yes	The account that owns the Workspace, with its user_id and email.
`created_at`	Yes	When the Workspace was created.
`updated_at`	Yes	When it last changed.
`main_session_id`	Yes	The main conversation id.
`current_revision`	Yes	The saved revision of the Workspace's current files; read_workspace_file reads it by default.
`default_agent_id`	Yes	The Workspace's agent: it runs the messages sent to this Workspace. Every Workspace has one; it is null only once the Workspace is deleting or deleted.
`storage_readiness`	No	Present while the Workspace's storage is still starting: state, since, pending_reason, retryable.
`root_working_copy_id`	Yes
`default_manager_agent_id`	Yes	The same value as default_agent_id.

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.17.1Oct 18, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Beyond the annotations (destructiveHint, idempotentHint, openWorldHint=false), the description discloses the agent-creation side effect and limit consumption, the 24-hour idempotency contract including the 422 idempotency_key_reused failure, that the call returns only after the first revision exists, that no run starts, that names are not unique, and the third-party data flow to OpenRouter, OpenAI, DeepSeek, Anthropic and TypeSafe.

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

Conciseness3/5

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

The definition is front-loaded with the core purpose, but it is a long block in which several sentences are marginal, notably the full provider roster, the note that the catalog can change, and the remark that runs generate no video. Those details dilute an otherwise efficient description.

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?

An output schema exists, so return values need no explanation, and the description still covers limits, agent creation, idempotency, timing of return, and the fact that no run is started. Nothing needed to invoke this creation call correctly is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely extends the schema: it explains the reuse-with-different-arguments refusal for idempotency_key and the create-new-agent-vs-select-existing choice for default_manager_agent_id. It adds meaning rather than restating field text.

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?

The opening sentence states a specific verb and resource and immediately defines what a Workspace is: durable files with saved revisions, a main conversation and run history. No sibling tool creates a Workspace, so the agent can distinguish this call from create_workspace_worker and the run-level tools without opening a schema.

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?

It gives decision-relevant context: omitting default_manager_agent_id also creates an agent that counts against the agent limit, while passing it selects an existing agent, and an idle agent costs nothing. It never names an alternative tool or an explicit when-not-to-use condition, so it stops short of full routing guidance.

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