Playbook

Add asset permalinks

add_asset_permalinks

Give assets a permalink: a permanent, PUBLIC URL that needs no login and never expires, unlike the signed display_url, which dies at the end of the next day. Use it when a URL has to keep working — an external site, a deck, a doc, a hand-off to another system. Publishing is the point: the file is copied to a public bucket and anyone holding the URL can fetch it, so a sensitive file becomes public. It serves files, not web pages: an HTML file behind a permalink is sandboxed and its scripts never run, so never use it to host a page or app — deploy_app is for that. The copy runs in the background. This call waits up to about 20 seconds for it and returns the finished URLs under created; anything still copying comes back under pending with no URL. Read those with get_asset_permalinks shortly after — never publish them again; a URL does not work until it is reported there. A large video can take minutes. Assets that already have one are left untouched and are NOT in created — they are listed under already_had_permalink; read their URL with get_asset_permalinks. Assets that all already have one publish nothing and come back listed under already_had_permalink, not as a failure. A permalink only exists for real uploaded files: a link asset, a note, a colour swatch, or an upload still ingesting (is_skeleton: true) is listed under no_file_to_publish and nothing is created — poll get_asset until the upload finishes before asking. failed_to_publish means the file could not be copied at all and the permalink was withdrawn; retrying will not help. Capped per plan (10 Free, 100 on trials, 1,000 Pro, 5,000 Team/Business); going over returns 422 and publishes NOTHING — the whole batch is refused, not the overflow, and the count is taken before the unpublishable assets are skipped, so near the cap send only real files. If the call fails partway, the response still reports what was published or queued plus a remaining list — call again with exactly that list, never with the original one. Send the whole set in one call, up to 200 tokens. The response reports quota after the writes, and list_organizations reports the same headroom without publishing anything, so check it there before a batch you are not sure fits. Requires write scope and update permission on every asset; one unknown token fails the whole call.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`asset_tokens`	Yes	Asset tokens to give a permalink (max 200 per call). Tokens that already have one are skipped. If the response carries `remaining`, call again with exactly those tokens.
`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.

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedOct 5, 2026

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

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: -[
-  "asset_tokens",
-  "context"
-]New value: +[
+  "asset_tokens"
+]

First observedOct 2, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Goes far beyond the annotations: it discloses the public-exposure consequence (a sensitive file becomes public), the sandboxing of HTML, the background copy with a ~20s wait and a `pending` class, quota caps per plan with whole-batch 422 refusal, partial-failure `remaining` semantics, write-scope and per-asset permission requirements, and the rule that one unknown token fails everything. Annotations only give readOnly/destructive/openWorld/idempotent hints; this description supplies the operational reality.

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?

The single dense paragraph is well front-loaded: purpose, then public-URL warning, then serving limits, then async/return-shape semantics, then edge cases and quota. Nearly every sentence carries decision-relevant information, but the wall-of-text form makes it harder to scan than it needs to be for the volume of distinct edge cases packed in.

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?

No output schema exists, so the description carries the full burden of return semantics and does so completely: it enumerates `created`, `pending`, `already_had_permalink`, `no_file_to_publish`, `failed_to_publish`, `remaining`, and `quota`, and explains what each means and what the agent should do next. For a batch mutation with async completion and partial failure, this is the required level of detail.

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 schema already documents both parameters, giving a baseline of 3. The description adds genuine semantics beyond it: the whole set must be sent in one call (not fanned out), the max-200 limit, that tokens already permalinked are skipped, and that a retry must use exactly the `remaining` token list. It also explains when to pass `organization` versus omitting it.

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+resource ('give assets a permalink') and immediately defines what a permalink is and how it differs from the signed display_url. It also carves out what it is NOT for (hosting pages/apps) and names the sibling that handles that case. An agent can distinguish it from get_asset_permalinks, deploy_app, and share_asset from the first two sentences.

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?

Explicit when-to-use ('when a URL has to keep working — external site, deck, doc, hand-off') and explicit when-not-to-use ('never use it to host a page or app — deploy_app is for that'). It routes the agent to the correct follow-up (get_asset_permalinks to read URLs) and the correct pre-check (list_organizations for quota) rather than re-publishing.

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?