Plori

Official

by plori-ai

Overview Schema Source Related Servers Discussions Admin

JavaScript

Remote

Upload Workspace file

upload_workspace_file

Destructive

Write a file to a Plori Workspace, replacing any file at that path. Send small UTF-8 text directly; for larger or binary files, get a single-use upload URL and curl command.

Instructions

Write a file into a Workspace's current files, replacing any file at path. For UTF-8 text up to 262144 bytes, pass it as content: the file is written before the call returns. For a larger or binary file, omit content: the call returns upload_url and a curl command that uploads one local file of up to 33554432 bytes (32 MiB). Run the command in a shell within 10 minutes. The URL needs no other credential and accepts one upload. While a run uses the Workspace's files, the write is refused with 409 agent_busy. Try again after the run ends. Members and viewers of a shared Workspace cannot write files (403).

Input Schema

Name	Required	Description
`path`	Yes	The file's path, relative to the Workspace root, for example docs/notes.md. Missing directories are created.
`content`	No	The file's UTF-8 text, up to 262144 bytes. Omit it, or pass an empty string, to get an upload URL instead.
`workspace_id`	Yes	The Workspace UUID.

Output Schema

Name	Required	Description
`path`	Yes	The file's path, from the Workspace root.
`size`	No	The bytes written, when written is true.
`command`	No	The curl command that uploads the file: replace LOCAL_FILE with the local file's path and run it in a shell.
`written`	Yes	True when content was written to the file. False when the call returned an upload URL instead.
`max_bytes`	No	The largest file upload_url accepts, in bytes.
`expires_at`	No	When upload_url stops being accepted.
`upload_url`	No	The URL that accepts one upload of the file as multipart form part file. It needs no other credential.
`workspace_id`	Yes	The Workspace UUID.

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.17.1Oct 18, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations only declare the safety profile (destructive, non-idempotent); the description adds substantial context beyond them — overwrite behavior, exact byte limits, a 10-minute/one-shot unauthenticated upload URL, and the 409 agent_busy conflict with retry guidance. This is the full behavioral picture an agent needs before invoking.

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

Conciseness5/5

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

Dense but every sentence carries a distinct operational fact (mode, size limits, URL lifetime, conflict, permission), and the core write action is front-loaded ahead of the edge cases.

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 here; the description instead covers the non-obvious prerequisites and failure modes. For a destructive write with three parameters, nothing needed to call it 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 would be 3, but the description adds genuine mode-selection semantics: omitting or emptying content switches the tool to returning upload_url rather than writing, with the size threshold that decides it. The schema documents fields individually but not this cross-parameter behavior.

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 ('Write a file into a Workspace's current files') plus the overwrite semantic ('replacing any file at path'). This clearly distinguishes it from the sibling read_workspace_file without needing to open either schema.

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?

Explicitly splits usage into two modes and names the condition that selects each: pass content for UTF-8 text up to 262144 bytes, omit content for larger or binary files. It also names failure conditions (409 agent_busy while a run uses files, 403 for members/viewers) and the retry action, leaving nothing to inference.

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