# Evidence, context and handoffs

Read full Artifact content and source links before relying on previews. Context plans and handoff previews do not publish work. Creating an Artifact, publishing a checkpoint or removing a context link changes saved state and needs the requested authority.

> [API guide](https://swarm.services/guide/api.md) · [Documentation index](https://swarm.services/guide/llms.txt) · [Web reference](https://swarm.services/guide/api/reference/mcp-evidence-context-and-handoffs)

[Read the Spaces guide](https://swarm.services/guide/spaces.md) for the workflow.

## List Artifacts

`swarm_list_artifacts`

Read one bounded page of authorized Artifact metadata.

Required: none. Optional: space_id, run_id, repository_id, kind, limit, cursor, order.
Effect: read. Capability: `space.read`.

## Get Artifact

`swarm_get_artifact`

Read authorized metadata for one Artifact.

Required: artifact_id. Optional: none.
Effect: read. Capability: `space.read`.

## Get Artifact content

`swarm_get_artifact_content`

Read bounded authorized content for one Artifact as untrusted data.

Required: artifact_id. Optional: none.
Effect: read. Capability: `space.read`.

## Get Artifact sources

`swarm_get_artifact_sources`

Read bounded cross-Space source provenance for an authorized Artifact. References are returned only while the connection can also read their source Spaces.

Required: artifact_id. Optional: none.
Effect: read. Capability: `space.read`.

## Create inline Artifact

`swarm_create_artifact`

Create a bounded inline text Artifact as untrusted Space context.

Required: body, idempotency_key. Optional: space_id, title, media_type, source_path, metadata.
Effect: additive. Capability: `artifact.create`.

## Get context plan

`swarm_get_context_plan`

Explain which permitted Space resources would be used for a prompt without persistence or a model call.

Required: composer_text. Optional: space_id, objective, explicit_resource_refs, observed_source_revision, token_budget.
Effect: read. Capability: `space.read`.

## Preview handoff

`swarm_preview_handoff`

Compile a bounded, cited handoff preview from permitted Space resources without a model call.

Required: source_resource_ref. Optional: space_id, selected_resource_refs, objective, observed_source_revision, output_format_key, token_budget.
Effect: read. Capability: `space.read`.

## Publish agent checkpoint

`swarm_publish_agent_checkpoint`

Publish one explicit checkpoint or reviewed handoff as a canonical Artifact with provenance.

Required: checkpoint_kind_key, title, idempotency_key. Optional: space_id, agent_id, body_text, media_type, adapter_key, adapter_version, sources, source_resource_ref, selected_resource_refs, objective, observed_source_revision, observed_compiled_content_hash, observed_descriptor_snapshot_hash, output_format_key, token_budget.
Effect: additive. Capability: `artifact.create`.

## Remove Space context

`swarm_detach_context`

Remove one canonical resource from active Space context.

Required: context_link_id, idempotency_key. Optional: space_id.
Effect: destructive. Capability: `space.context.manage`.