Playbook

Finish upload

finish_upload

Step 2 of 2: turn bytes you have already sent to storage into a Playbook asset. Call it only after every step returned by create_upload_url has succeeded — this call does not transfer anything, it records what landed. Pass the signed_gcs_id from create_upload_url unchanged. If a step failed, do NOT call this; start over with a fresh create_upload_url.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "signed_gcs_id": "<signed_gcs_id>",
      "media_type": "<media_type>"
    },
    "name": "finish_upload"
  }
}

Input Schema

Name	Required	Description
`size`	No	Byte size, as passed to create_upload_url
`title`	No	Asset title. Pass the same filename you gave create_upload_url — it is NOT remembered between the two calls, and omitting it creates an untitled asset.
`width`	No	Pixel width, if known. Do not guess.
`height`	No	Pixel height, if known. Do not guess.
`media_type`	Yes	MIME type of the stored file. Required, and it must be the SAME value you gave when you asked for the upload address — nothing is carried between the two calls, so a different value here labels the asset as something the stored bytes are not.
`description`	No	Optional description
`ai_generated`	No	Mark the asset as produced by an AI tool. On this upload path the flag does more than label it: it also suppresses automatic duplicate merging and grouping, which matters when you are pushing many variants of one image. It only has that effect when set HERE, at creation — setting it later records the marker but cannot un-merge anything.
`organization`	No	Workspace slug, as returned by list_organizations. Omit it when the account has a single workspace — it is then resolved from your token. Pass it only when the account has several, or when you mean a workspace other than the obvious one.
`signed_gcs_id`	Yes	The value create_upload_url returned. Pass it back exactly, it is signed.
`ai_agent_payload`	No	Free-form JSON metadata stored with the asset — for example generation settings such as model and seed, or a source job id. Playbook never interprets it. Max 4096 BYTES of serialised JSON; anything larger is REJECTED, never truncated. A write REPLACES the whole object. Readable per asset (get_asset, or list/search with get_ai_payload=true) but NOT searchable or filterable.
`collection_token`	No	Destination board token. If omitted or unknown, Playbook silently routes to a default anonymous board — call get_board first to validate.

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedNov 3, 2026
- removedInput schema / additionalProperties
```
Removed value: -false
```
- addedInput schema / properties / ai_agent_payload / propertyNames
```
Added value: +{
+  "type": "string"
+}
```
- addedInput schema / properties / height / maximum
```
Added value: +9007199254740991
```
- addedInput schema / properties / size / maximum
```
Added value: +9007199254740991
```
- addedInput schema / properties / width / maximum
```
Added value: +9007199254740991
```

Changed4 schema fields changedOct 5, 2026

addedInput schema / additionalProperties
```
Added value: +false
```

changedInput schema / properties / ai_agent_payload / description

Previous value: -"Your own scratch space on this asset — prompt, model, seed, source job id, anything you need to recognise it in a later session. Playbook never interprets it. Max 4096 BYTES of serialised JSON; anything larger is REJECTED, never truncated. A write REPLACES the whole object. Readable per asset (get_asset, or list/search with get_ai_payload=true) but NOT searchable or filterable."New value: +"Free-form JSON metadata stored with the asset — for example generation settings such as model and seed, or a source job id. Playbook never interprets it. Max 4096 BYTES of serialised JSON; anything larger is REJECTED, never truncated. A write REPLACES the whole object. Readable per asset (get_asset, or list/search with get_ai_payload=true) but NOT searchable or filterable."

removedInput schema / properties / context

Removed value: -{
-  "description": "Explain why you are calling this tool and how it fits into the user's overall goal. This parameter is used for analytics and user intent tracking. YOU MUST provide 15-25 words (count carefully). NEVER use first person ('I', 'we', 'you') - maintain third-person perspective. NEVER include sensitive information such as credentials, passwords, or personal data. Example (20 words): \"Searching across the organization's repositories to find all open issues related to performance complaints and latency issues for team prioritization.\"",
-  "type": "string"
-}

changedInput schema / required

Previous value: -[
-  "signed_gcs_id",
-  "media_type",
-  "context"
-]New value: +[
+  "signed_gcs_id",
+  "media_type"
+]

First observedOct 2, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=false, and idempotentHint=false. The description adds real context beyond them: this call performs no transfer, it only records what already landed; it requires the signed_gcs_id unchanged; and failed prerequisites mean restart rather than retry. The one gap is that with idempotentHint=false the description never warns that a repeated finish_upload call may create a second asset.

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?

Four short sentences, front-loaded with the step number so the ordinal context lands first. Each sentence carries a distinct operational fact: what it does, when to call, what to pass, and what to do on failure. No filler.

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?

The tool has 11 parameters (2 required), a nested object, and no output schema, so the description should ideally say what comes back (the created asset/ID) now that the write has landed. It covers the workflow and the prerequisite chain thoroughly, but omitting the return value for a creation endpoint with no output schema is a real, if modest, gap.

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 per-asset parameter semantics are already fully documented, including the ai_generated merge-suppression behavior and the ai_agent_payload size limit. The description reinforces the signed_gcs_id passthrough but adds little that the schema does not already say; baseline 3 applies.

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 outcome: 'turn bytes you have already sent to storage into a Playbook asset,' and frames it as 'Step 2 of 2' relative to create_upload_url. An agent can immediately distinguish this from create_upload_url, finish_uploads, and upload_from_url.

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 explicit preconditions ('only after every step returned by create_upload_url has succeeded'), an explicit exclusion ('If a step failed, do NOT call this'), and the recovery path ('start over with a fresh create_upload_url'). Nothing about when to invoke is left to inference.

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

All Playbook tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?