# Answers, intelligence and provenance

Inspect registered contracts and stored evidence before asking for an answer or recording a trace. Ask Space creates a durable answer and optional learning work; it is not a read. Projections, candidates, promotion gates and traces report recorded state, not verified truth or new authority. Corrections and supersession need explicit review evidence.

> [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-answers-intelligence-and-provenance)

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

## Get answer contract

`swarm_get_answer_contract`

Read the canonical answer contract for a Space.

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

## List Space answers

`swarm_list_answers`

Read one bounded page of authorized Space answers.

Required: none. Optional: space_id, confidence, visibility, limit, cursor, order.
Effect: read. Capability: `space.read`.

## Get Space answer

`swarm_get_answer`

Read one authorized Space answer.

Required: answer_id. Optional: space_id.
Effect: read. Capability: `space.read`.

## Ask Space

`swarm_ask_space`

Create one durable answer grounded only in promoted Space memory. When allow_learning_update is permitted and true, this also queues learning work.

Required: question, idempotency_key. Optional: space_id, objective, constraints, desired_output_shape, allow_learning_update.
Effect: additive. Capability: `space.operate`.

## Get decision graph

`swarm_get_decision_graph`

Read the canonical bounded decision graph for a Space.

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

## Get Action Intelligence

`swarm_get_action_intelligence`

Read one bounded action-provenance summary for an authorized Space.

Required: none. Optional: space_id, start_at, end_at, trace_limit.
Effect: read. Capability: `space.operate`.

## List action traces

`swarm_list_action_traces`

Read one bounded page of authorized action provenance for a Space.

Required: none. Optional: space_id, run_group_id, run_id, execution_id, actor_identity_id, agent_id, core_id, command_id, model_call_id, trace_root_id, parent_trace_id, action_descriptor_key, status, evidence_class_key, capture_profile_key, coverage_key, start_at, end_at, limit, cursor, order.
Effect: read. Capability: `space.operate`.

## Get action trace

`swarm_get_action_trace`

Read one authorized action trace with bounded canonical resource links.

Required: trace_id. Optional: none.
Effect: read. Capability: `space.operate`.

## Append action trace batch

`swarm_append_action_trace_batch`

Append bounded client-reported, non-Run action provenance for the connected client.

Required: trace_root_id, events, idempotency_key. Optional: space_id, agent_id, capture_profile_key, coverage_key, adapter_key, adapter_version.
Effect: additive. Capability: `agent.operate`.

## List Space operations

`swarm_list_operations`

Read one bounded page of authorized Space operations.

Required: none. Optional: space_id, operation_kind, capability_key, status, limit, cursor, order.
Effect: read. Capability: `space.read`.

## Get operation contract

`swarm_get_operation_contract`

Read one registered Space operation contract.

Required: operation_kind. Optional: space_id.
Effect: read. Capability: `space.read`.

## Get Space operation

`swarm_get_operation`

Read one authorized Space operation.

Required: operation_id. Optional: space_id.
Effect: read. Capability: `space.read`.

## List intelligence projections

`swarm_list_projections`

List one page of saved knowledge summaries (projections), with source Artifact IDs, validation scores and status. Filter by family or status; no recomputation.

Required: none. Optional: space_id, family, status, limit, cursor, order.
Effect: read. Capability: `space.read`.

## List learning queue

`swarm_list_learning_queue`

Read one bounded page of authorized learning queue items.

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

## List learning candidates

`swarm_list_learning_candidates`

Read one bounded page of authorized learning candidates.

Required: none. Optional: space_id, status, family, limit, cursor, order.
Effect: read. Capability: `space.read`.

## Get learning frontier

`swarm_get_learning_frontier`

Summarize Space learning queues, candidate and projection statuses, promotion decisions and validation scores from stored records. Does not start learning.

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

## List promotion gates

`swarm_list_promotion_gates`

Read one bounded page of authorized promotion decisions.

Required: none. Optional: space_id, decision, candidate_id, projection_id, limit, cursor, order.
Effect: read. Capability: `space.read`.

## Correct learning candidate

`swarm_correct_learning_candidate`

Create a new evaluated learning candidate linked to an immutable source candidate.

Required: candidate_id, summary, reason, idempotency_key. Optional: space_id.
Effect: additive. Capability: `space.learning.review`.

## Supersede learning candidate

`swarm_supersede_learning_candidate`

Supersede or mark stale a learning candidate with explicit review evidence.

Required: candidate_id, reason_key, reason, idempotency_key. Optional: space_id, replacement_candidate_id.
Effect: control. Capability: `space.learning.review`.