Particles

Rank undeposited URLs the corpus frequently cites (read-only). Surfaces primary sources the corpus leans on but has never deposited — "hearsay vs. primary source" gaps — ranked by trust-weighted distinct-source diversity × recency. Read-only: the ``dismiss`` half of the workflow lives on the CLI / HTTP API. Args: limit: Maximum suggestions to return. Defaults to ``citation_signal.rank_cap`` when omitted. min_sources: Minimum distinct citing sources required to surface a URL. Defaults to ``citation_signal.min_distinct_sources`` when omitted. Returns: ``{suggestions, total_candidates, capped}`` matching the ``DepositSuggestReport`` schema.

Show one operator event in full — header, refs, and payload. Args: event_id: The event's id.

List operator events, newest first, optionally filtered. Args: particle: Only events touching this particle id. subject: Only events touching this subject id. corpus_entry: Only events touching this corpus entry id. (At most one of ``particle`` / ``subject`` / ``corpus_entry``.) event_type: Only events of this type, e.g. ``SOURCE_RETRACTED``, ``SUBJECTS_SPLIT``, ``TRUST_CHANGED``, ``REVIEW_RESOLVED``. limit: Maximum events to return (default 50).

Render one scoped epistemic subgraph of the particle store. Scope is mandatory — pass exactly one of ``subject_id`` / ``query`` / ``inconsistency_id`` / ``manifest``+``section`` (a whole-store render does not exist; the anti-hairball invariant). Every epistemic quantity in the result (effective confidence, contested badges, as-of visibility, utility evidence) is computed at render time by the engine and never stored. Args: subject_id: Neighbourhood scope — this Subject, its particles, and subjects reachable within ``hops`` via multi-subject particles. Accepts a subject id or an exact (case-insensitive) canonical name / alias; the render's ``scope_ref`` is the resolved id. query: Retrieval-set scope — the top-K hits of the existing query ranking rendered as their subjects plus the hit particles ("the picture of the knowledge the agent consulted"). inconsistency_id: Evidence scope — a contradiction's picture: the INCONSISTENCY particle as the anchor, its two disputant beliefs shown with their true statuses (the quarantined side included), their subjects and sources. Accepts a full particle id or a unique prefix (a contested badge's ``inconsistency_id`` is the usual source). manifest: With ``section``, projection scope — an manifest section's deterministic selection rendered as a graph. The manifest is a relative name under the engine's ``graph.manifest_root``; with that unset the scope is refused. section: The manifest section's ``region`` id, or its exact (case-insensitive) title. hops: Neighbourhood radius for subject scope (clamped to ``graph.max_hops``). history: Also include retired supersession-chain ancestors, rendered as ghosts. as_of: ISO-8601 past instant (a bare date means start of that day, UTC): render the graph as believed at T. A future instant is rejected. max_nodes: Per-c…

Propose co-evidential candidate pairs within Subjects (read-only). Within each Subject, ACTIVE particles whose embeddings exceed the similarity threshold and are not already linked CO_EVIDENTIAL are surfaced as candidate pairs for operator review. No LLM call, no mutation — this is the ``REPORT`` mode of ``particles links suggest``. Args: subject_id: Restrict to one Subject. ``None`` scans every Subject — prefer passing a ``subject_id`` to keep results focused. threshold: Cosine-similarity floor (0.0–1.0). Defaults to ``links_suggest.candidate_threshold`` when omitted. limit: Maximum candidate pairs to include across all clusters (default 100). A ``truncated`` flag is added when the cap fires. Returns: ``{run_at, mode, clusters, total_candidates, warnings}`` matching the ``SuggestReport`` schema, optionally with ``truncated: True``.

Run structural lint checks over the particle store (no fixes, no LLM). The MCP surface is read-only, so ``--fix`` is forced off and the LLM-assisted semantic checks are disabled — agents read findings and surface them to the operator, who decides whether to act. Args: category: Optional ``finding_type`` filter (e.g. ``STALENESS``, ``PHANTOM_SUBJECT``, ``WIKIDATA_LINK_MISMATCH``). When set, only findings of that kind are returned; ``summary`` is always the full counts dict and reflects every category actually emitted by this run. summary_only: When ``True``, drop the ``findings`` list and return only the ``summary`` counts dict (plus ``run_at``). Useful when the agent only needs to know what *kinds* of problems exist before drilling in with ``category``. limit: Maximum findings to include after filtering (default 100). Hard cap to keep the response under per-tool-result size limits even when many findings of one category exist. A ``truncated`` flag is added when the cap fires. Returns: ``{run_at, findings, summary}`` matching the ``LintReport`` schema, optionally with ``truncated: True`` and (when ``summary_only``) without the ``findings`` key.

List recent corpus entries (most-recently-deposited first). Args: limit: Maximum entries to return (default 50). source_type: Optional filter (e.g. ``"WIKIDATA_API"``).

List every taxonomy + its full tag tree. Args: limit: Maximum taxonomies to return (default 50). Each taxonomy embeds its full tag tree, so even a handful of large taxonomies can push the response past the per-tool-result token cap. offset: Number of taxonomies to skip before returning results (default 0). Results are ordered by name so pagination is stable.

List particles sharing a context fingerprint. Args: fingerprint: Full 64-char SHA-256 hex or a prefix (≥ 8 chars). limit: Maximum particles to return (default 50, capped at 200 to keep responses within MCP per-tool-result token caps — fingerprint matches share full ``content`` strings). 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 ``fingerprint`` (the queried value) and ``particles`` (list of ``{id, status, content}`` summaries).

Show one particle with its provenance, subjects, and tags. Args: particle_id: Full UUID or unambiguous prefix (≥ 8 chars). Returns: Dict with ``particle`` (Pydantic JSON), ``subjects`` (list of ``{id, canonical_name}``), and ``provenance`` (list of ``{type, corpus_entry_id, uri_r, source_type, snapshot_id}``). When the source now states the claim in other words, ``restated_as`` holds that wording and its snapshot; the claim's ``content`` keeps its first wording. Raises if the prefix matches zero or multiple particles.

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 inte…

Return the extraction-quality dashboard snapshot. Particle counts by status / calibration_source / schema_version, plus the structural-mix percentages, the store's recorded LLM spend (``llm_spend``), and the curation queue's precision over the default window (``curation_precision``: per card kind, the cards acted on, dismissed, snoozed and untouched, with the denominator). Computed entirely from live DB queries — no LLM involvement.

Run a tag-aware semantic query against the particle store. Args: question: Natural-language question. Optional since: omit it and set structural claim filters (or an aggregate / the predicate listing) for the deterministic modes — no embedding, no LLM call. tags: Subtree-expanded tag filters, repeatable. subject_id: Restrict to particles about this subject. min_confidence: Minimum confidence value (0.0–1.0). top_k: Number of particles to retrieve (1–200). audience: "GENERAL" | "EXPERT" | "REGULATORY". summary: When ``True``, each hit in ``particles`` is reduced to ``{id, content, confidence, effective_confidence, subject_ids}`` — provenance, tags, properties, and embeddings are dropped. The NL ``answer`` string and coverage gaps are unchanged. Use this when the agent only needs to surface the answer and pick particles to ``particle_show`` later. Default ``False`` preserves the full ``QueryResponse`` shape for backward compatibility. as_of: ISO-8601 past instant (a bare date means start of that day, UTC): answer what the store believed at T. Retired hits carry an ``as_of_notes`` entry (current status, retirement instant + basis, and the superseding belief); ``as_of_excluded_undatable`` discloses retirements the store cannot date. A future instant is rejected. during_start: With ``during_end``, a window of world time (ISO-8601 dates, inclusive; either may be omitted for an open end): answer about what began in, or was in force during, that period. The window prefilters the candidate set before ranking; with no question it returns the claims in date order, each with a ``window_hits`` reading (``BEGAN``, ``IN_FORCE``, ``HELD_AT``, ``WITHIN``). A retired claim is admitted for the period it held, marked with its retirement and its close. Reads ``valid_from``; ``…

List subjects in the knowledge graph (alphabetical by canonical_name). Paginated to keep responses within an MCP-client-friendly size — the full subject set can easily exceed per-tool-result token caps. Args: limit: Maximum subjects to return (default 50). offset: Number of subjects to skip before returning results (default 0). Combine with ``limit`` to page through the full set. order: ``"name"`` (alphabetical, default) or ``"degree"`` — most-connected first, by descending count of ACTIVE particles linked to each subject (name tie-break). Use ``"degree"`` to find a store's hub subjects, e.g. as a ``graph_view`` starting scope.

Substring search over subject names and aliases (case-insensitive). Args: query: Substring to match against ``canonical_name`` or any recorded alias, so "speaker" finds a subject whose alias is "the speaker". limit: Maximum subjects to return (default 50). A generic substring like "the" can match thousands of subjects, so this caps the page size. offset: Number of matches to skip before returning results (default 0). Results are alphabetical by canonical_name so pagination is stable.

Show one subject with the particle IDs linked to it. Args: subject_id: A full UUID, an unambiguous prefix (≥ 8 chars), or a name or alias, matched case-insensitively and exactly. A reference that matches more than one subject (a prefix shared by several IDs, a name two subjects share, or a string that is both a prefix and a name) raises with the candidates named. A remote engine resolves IDs and prefixes only. particle_id_limit: Maximum particle IDs to include in ``particle_ids`` (default 100). For hot subjects the full list can blow the per-tool-result token cap; use ``particles_list(subject_id=…, limit=…, offset=…)`` for the full set when ``particle_count > particle_id_limit``. Returns: Dict with ``subject`` (Pydantic JSON), ``particle_ids`` (capped at ``particle_id_limit``, ordered by id for stable pagination), and ``particle_count`` — the true total of linked particles, so callers can detect when the list was truncated.