cozyvtt-mcp

Document Upload

document_upload

Upload a local PDF, TXT, or MD file to create a document asset. Specify scope (user, campaign, or global) and optional name, tags, and description for the upload.

Instructions

Upload an existing local PDF/txt/md file as a document asset using multipart REST. Use document_create for inline text, or document_share to link an existing asset. Reads the MCP server/container filesystem; client-local paths must be mounted. Creates an asset on each accepted call, so retries may duplicate it. Scope controls access: CAMPAIGN requires that campaign's DM; other scope rights are upstream-enforced. The server checks signatures and its size cap (default 50 MiB), with a shared upload/create limit of 30/minute/user by default. A 400 is preserved without fallback upload. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`name`	No	Optional asset display name; null omits it so upstream uses its upload default.
`tags`	No	Optional tag strings joined by commas for multipart upload; null omits tags, while [] sends an empty field.
`scope`	No	Visibility/ownership scope: USER (default personal), CAMPAIGN, or GLOBAL; upstream enforces creation rights. CAMPAIGN uses campaign_id.	USER
`file_path`	Yes	Existing .pdf/.txt/.md path on the MCP server filesystem; ~ is expanded. Container users must mount the file.
`campaign_id`	No	Explicit campaign ID; null uses the configured campaign when scope=CAMPAIGN, otherwise omits the field. If supplied, it is forwarded for any scope.
`description`	No	Optional asset metadata text; null omits it. Upstream validates upload metadata.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.3.0Sep 20, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations only mark side effects and idempotency; the description adds major operational detail: retries duplicate assets, CAMPAIGN scope requires the DM, signature/size-cap checks, default 30/min rate limit, 400 preservation, and exact success/failure response shapes. This is far beyond annotation coverage.

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?

Though long, every sentence carries a distinct operational fact: purpose, alternatives, filesystem constraint, idempotency warning, access control, limits, error behavior, and return format. It is front-loaded with purpose and routing and contains no filler.

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?

For a mutating, non-idempotent upload tool with 6 parameters, this description covers file source prerequisites, permissions, rate limits, duplication risk, return values, and error classification. Output schema exists and is further supplemented by explicit response documentation, so nothing an agent needs to invoke 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% with rich parameter descriptions, so the baseline is 3. The description adds extra meaning for scope (CAMPAIGN requires that campaign's DM) and file_path (size cap and signature checks), justifying a small bump above baseline.

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 specifies the exact operation: uploading an existing local PDF/txt/md file as a document asset via multipart REST. It also differentiates from siblings by naming document_create for inline text and document_share for linking existing assets, so an agent can select the right tool.

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?

The description gives explicit routing guidance: use document_create for inline text, document_share for linking existing assets, and this tool when uploading a file. It also states the filesystem prerequisite ('client-local paths must be mounted'), which is a clear when-not condition.

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