Swarm

Preview handoff

swarm_preview_handoff

Read-onlyIdempotent

Render cited Markdown from readable sources without saving or a model call. Returns coverage, source revision and review hashes; required sources must fit token_budget. Use swarm_get_context_plan to select prompt context. Publishing needs write access.

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": {
      "source_resource_ref": "<source_resource_ref>"
    },
    "name": "swarm_preview_handoff"
  }
}

Input Schema

Name	Required	Description
`space_id`	No	Space ID from swarm_list_spaces; omit if sole.
`objective`	No	Purpose guiding context selection within your access.
`token_budget`	No	Approximate token ceiling, 1-32000; default 8000. Selected sources must fit or the preview fails.
`output_format_key`	No	prompt.markdown, or omit for the default.
`source_resource_ref`	Yes	Primary reference, such as artifact:<id>, from authorized reads.
`selected_resource_refs`	No	Additional readable source references.
`observed_source_revision`	No	source_revision from the latest preview; stale publishing fails.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 schema fields changedOct 29, 2026

addedInput schema / properties / objective / description

Added value: +"Purpose guiding context selection within your access."

addedInput schema / properties / observed_source_revision / description

Added value: +"source_revision from the latest preview; stale publishing fails."

addedInput schema / properties / output_format_key / description
```
Added value: +"prompt.markdown, or omit for the default."
```
addedInput schema / properties / selected_resource_refs / description
```
Added value: +"Additional readable source references."
```

addedInput schema / properties / source_resource_ref / description

Added value: +"Primary reference, such as artifact:<id>, from authorized reads."

changedInput schema / properties / space_id / description

Previous value: -"Omit for a single approved Space."New value: +"Space ID from swarm_list_spaces; omit if sole."

addedInput schema / properties / token_budget / description

Added value: +"Approximate token ceiling, 1-32000; default 8000. Selected sources must fit or the preview fails."

Changed1 schema field changedOct 29, 2026
- addedInput schema / properties / space_id / description
```
Added value: +"Omit for a single approved Space."
```
First observedOct 28, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Goes well beyond the readOnly/idempotent annotations: no model call, nothing persisted, returns coverage plus source revision and review hashes, and names two failure modes (sources exceeding token_budget, stale observed_source_revision). This is exactly the extra context annotations cannot carry.

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?

Three short sentences, zero filler, with the core capability and its two most important constraints front-loaded. Each sentence carries distinct information.

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?

With a full input schema, an output schema, and rich annotations, the description supplies what structured fields cannot: the no-side-effect guarantee, the budget failure condition, and the staleness check. Nothing an agent needs to invoke 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 is 3, and the description adds real semantics on top: token_budget is a hard ceiling that fails the preview, and observed_source_revision staleness blocks publishing. Other parameters (space_id, objective, output_format_key) are left to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Render cited Markdown from readable sources') and immediately narrows scope with 'without saving or a model call', which distinguishes it from a publish operation. The 'handoff' framing in the name is never explained, but the operational purpose is unambiguous.

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?

Explicitly routes context selection to swarm_get_context_plan and notes that publishing requires write access, implying this preview is the pre-publish step. It gives clear usage context but does not state a hard when-not condition.

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

All Swarm 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.