particles_list
List particles by status or subject to get their IDs and summaries without loading full content. Filter for open inconsistencies, retracted items for cleanup, or active particles linked to a subject.
Instructions
List particles, optionally filtered by status or subject.
Lightweight alternative to ``query`` and ``lint`` when an agent
just needs the IDs of particles in a particular state — e.g. the
open INCONSISTENCY queue, RETRACTED particles for cleanup, or
every ACTIVE particle linked to a subject. Embeddings are never
included; responses are designed to stay within MCP tool-result
size caps.
Args:
status: Optional status filter — one of
``ACTIVE``, ``SUPERSEDED``, ``RETRACTED``,
``PROVENANCE_STALE``, ``INCONSISTENCY``. Unset returns
particles in any status.
subject_id: Optional subject: a full ID, an ID prefix,
or a name or alias, resolved as ``subjects_show`` resolves it.
When set, only particles linked to that subject via the
``particle_subjects`` join table are returned, and the result
echoes the resolved ``subject_id``. A reference that matches no
subject, or more than one, raises.
limit: Maximum particles to return (default 50). Must be > 0.
offset: Number of particles to skip before returning results
(default 0). Combine with ``limit`` to page through the
full set.
all_projects: On a server bound to one project, read the whole
store instead of that project's view. The result says so. No effect
on an unbound server.
Returns:
Dict with ``particles`` — a list of summary dicts containing
``id``, ``status``, ``content``, ``confidence``,
``subject_ids``, ``asserted_at``, and ``status_reason``. Each
entry's ``contested`` key is the id of an open INCONSISTENCY
referencing it, else null; ``contested_bases``
rides beside it with the fired basis labels —
composed by the same composer the ``query`` tool uses, so all
three bases (stance / divergence / inconsistency) are evaluated
and the two surfaces on one server always agree. Plus
``limit``/``offset`` echoed back so the agent can drive
pagination. Embeddings are intentionally omitted.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| status | No | ||
| subject_id | No | ||
| all_projects | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||