<!-- GENERATED — do not edit by hand. Source: noezis mcp schema / noezis inspect. Regenerate: make docs-reference. -->

Reference — MCP verbs

61 verbs exposed over JSON-RPC 2.0 (stdio). Each verb is callable by any MCP-capable agent. Grouped by capability tier.

Maturity note. The entity-relations verbs (noezis_relations, noezis_entity_neighbors, noezis_path_entities, noezis_chains, noezis_triplets, noezis_explain_chain) rely on an experimental named-entity layer that is de-scoped from retrieval: their reliability depends on entity-extraction quality on your corpus. Document retrieval (noezis_search, the tree, decisions) does not depend on this layer.

Read — inspection (no mutation)

noezis_audit_contradictions

Full graph scan to detect the contradictions between passages and active Decisions. Costly on a large corpus — reserve for periodic audits or after ingesting a whole corpus. Returns the tensions grouped by severity (critical/high/low).

When to use — To audit the contradictions in the whole graph. After ingesting a large corpus to see the detected inconsistencies.

noezis_briefing

[DEPRECATED — use noeziscontext] State-of-the-world summary: recent ADRs, active tensions, hot topics, codifications, paradigms. Kept as a transitional alias; will be removed at V-next. The state-of-world is now a section of noeziscontext (pushed at the start of the turn).

When to use — Do not use anymore for new code — see noezis_context. Alias maintained for compatibility of the deployed hooks/skills.

noezis_capabilities

Tool discovery by INTENT (ADR-0005): returns the catalog verbs relevant to a natural-language intent, ranked by overlap (name + description + usewhen), with their inputschema for direct call. Dynamic entry point to the long tail of tools (analogous to ToolSearch) — additive, does not replace tools/list. Pure read.

When to use — When you don't know which Noezis tool covers your need, or to find an uncommon advanced verb without browsing the whole catalog.

noezis_compare_registers

Compares two knowledge registers and detects the divergences: same concept, contradictory values between the two registers. Pure read — does not modify the graph. Emits a registers_compared OpEvent for the audit. Typically used to verify that the ADRs and the documentation stay consistent.

When to use — To audit the consistency between two registers (e.g.: architectural decisions vs documentation) before a merge or in a periodic audit.

noezis_context

SINGLE entry point for retrieving the project context. In one bounded call: store health, state-of-world (recent decisions/tensions + last handoff), search results on the query, and agentic skills to apply. The context is normally PUSHED automatically at the start of the turn (UserPromptSubmit hook) — only call this tool yourself if that context was not injected (fallback) or to refresh on a new query. Successor of inquire/briefing.

When to use — As a fallback if the context block was not injected at the start of the turn, or to target a new query. Replaces noezisinquire + noezisbriefing.

noezis_doc_audit

Audits a documentary scope on TWO axes: (1) the tensions ALREADY persisted in the graph (Pass3 contradictions, stale sections) filtered by path/topic; (2) de novo detection of doc↔code divergences (code_divergences field) — deterministic scan (without LLM) that confronts the symbols claimed by the doctrine (algos/libs/identifiers) with the real code and flags when the doc asserts X "bare" while the code uses a contradictor Y. Pure read — modifies neither the graph nor the files.

When to use — Before modifying doc, or in an anti-drift audit: see the recorded tensions AND the doc↔code gaps detected on the fly (direct filesystem scan, without prior ingestion).

noezis_doc_briefing

Briefing focused on the documentation: recent modifications, active tensions, potentially stale sections. Extension of noezis_briefing for the doc-maintenance agents. Pure read.

When to use — At the start of a doc-maintenance session — to quickly see what moved, what is in tension, and what could be stale.

noezis_doctor

Health report of the Noezis server: version, embedder mode, node counters (ready/indexing/failed), latest ingestion failures. Call at the start of a session to diagnose the store's state.

When to use — To diagnose the server's state, detect nodes stuck in INDEXING, or see the latest documents rejected by validation pipeline.

No parameters.

noezis_entities

Searches named entities in the graph by text/concept. Returns the entities whose name (raw or canonical) or kind contains the query. Sorted by decreasing confidence.

When to use — To find an entity (person, org, tech, product…) in the graph. Returns the EntityNodes with LID, canonical_name, kind, confidence.

noezis_explain_chain

Explains a chain of relations between entities with active tensions, aggregated confidence and sources: returns the path + the tensions on the chain + the total weighted confidence. Note: relies on the experimental entity-relations layer (de-scoped from retrieval) — reliability depends on entity-extraction quality.

When to use — After noezispathentities to get the full explanation of a path: tensions, sources, confidence. Usage: multi-hop reasoning.

noezis_gaps_report

Report of what the graph CANNOT answer (KL-1): distinct no_match search queries (with count and last occurrence), orphan entities (mentioned in passages but participating in zero typed relation), and Q5 routing misses (native search without noezissearch). Optional filters: since (default now − 14 days), maxmisses, max_entities (default 20, cap 50). Pure read — pull-only, never pushed.

When to use — To decide what to document next: the questions the graph keeps failing to answer and the concepts mentioned everywhere but defined nowhere. The MISS side of the usage telemetry.

noezis_get_paradigms

Returns all the active paradigms for a (subject, predicate): each paradigm = an active Decision of a distinct actor. Lets you see which actors have different views on the same subject without it being a contradiction — it's paradigm coexistence (T75 V2.5).

When to use — To inspect the coexisting paradigms on a subject. E.g.: user:alice says auth=OAuth2, agent:claude says auth=JWT → two paradigms, no conflict.

noezis_graph_report

Structural report of the graph: over-connected topics, communities, entropy ratio, suggested entry points, plus an entity_health audit (duplicates, type conflicts, garbage — the entity-layer doctor). Mode scope: "recent" (+ since_hours) returns only the recent activity — ideal for cold start. Mode scope: "full" (default) — full report.

When to use — At the start of a session (scope: "recent", since_hours: 24) to see what changed, or once at startup (scope: "full") to map the whole graph.

noezis_inquire

[DEPRECATED — use noeziscontext] Consults the Noezis graph on a topic and returns the context (results, tensions, paradigms). Kept as a transitional alias; will be removed at V-next. Prefer noeziscontext (store health + state-of-world + search + skills in one bounded call).

When to use — Do not use anymore for new code — see noezis_context. Alias maintained for compatibility of the deployed hooks/configs.

noezis_inquire_skip

Explicitly declares that no graph knowledge is relevant for this answer turn. Audit-grade traceability. To use only for the out-of-graph-scope queries (e.g.: 'what time is it?', pure computation). Never use to avoid a search on a documented subject.

When to use — When the question has nothing to do with the indexed documents. Provide an explicit reason.

noezis_list_tensions

Lists the graph's tensions with AND filters (since/until, register, status, minseverity). Severity derived from the kind (Direct=1.0, Structural=0.7, Inferential=0.4). Sorted severity DESC, tie-break edgeid lex DESC. Deterministic pagination via max_results (default 50, hard cap 200). Pure read.

When to use — To audit the active or resolved tensions of a register / a period, or sort by severity the conflicts to handle in priority.

noezis_list_watched

Lists the currently watched folders. Use to audit the watcher's state.

When to use — To audit the list of folders currently watched by the watcher.

No parameters.

noezis_node_summary

Returns a node's metadata from its identifier. By default, only the short summary is exposed (Document/passage); Decisions expose their full triple. Pass include_content: true to get the content — the FULL TEXT of the Document/passage, including when the source file is gone.

When to use — To read a node whose LID you have (from noezissearch or a navigation). Add includecontent: true for the full text.

noezis_op

Inspects a single event of the op-mem journal (OpEvent) from its hex 64 LID. Returns the full event: action, actor, targetlid, detailed metadata (BTreeMap), timestamp, contenthash. Typed refusal if the LID points to another kind (not_an_op_event). Pure read, no generation.

When to use — When you have already seen an OpEvent LID in another response (summary, history) and you want the full detail of a specific event.

noezis_op_history

Paginated search in the op-mem journal (OpEvent). Optional AND filters: actor (exact Principal), action (open catalog), targetlid (hex 64), since/until (inclusive-inclusive). Sorted DESC by timestamp, tie-break hex LID DESC. Hard cap 200 events per call (silent clamp). The response exposes `totalmatched, truncated, maxresultsused` for the audit. Pure read.

When to use — To audit the action trace (ingest, decided, toolinvoked) of an agent, or detect MCP catalog usage patterns via `action = 'toolinvoked'`.

noezis_pending_decisions

Returns the decisions awaiting validation: assertions blocked by conflict detection (kind: decision_blocked) and suggested non-asserted decisions (kind: decision_suggested). Lets the agent catch the weak signals detected but not committed in session. Pure read, sorted DESC by timestamp.

When to use — At the start or end of a session to check whether decisions were blocked or remain to be validated. Complement to noezis_briefing.

noezis_prefs_list

Lists the behavioural preferences stored for this workspace. Preferences are inferred from friction signals and govern how the agent should respond (tone, format, process). Filter by lifecycle: candidate | active | pinned | dormant.

When to use — To inspect what the workspace has learned about your working style, or before deciding whether to pin/drop a preference.

noezis_propose_decision

Dry-run of a Decision: simulates noezisassertdecision without committing. Returns the potential conflicts (conflict detection) and the coexisting paradigms BEFORE laying the decision. Use to check before asserting, especially if you are unsure whether a contradictory decision exists.

When to use — Before noezisassertdecision, to preview the conflicts. Returns would_conflict=true/false without mutating the graph.

noezis_read_sub_tree

Extraction of a 'semantic bubble' around a topic: searches the topic, then BFS-expands up to a token budget. Returns a complete focused context — ideal to quickly load the context on a concept before reasoning on it. By default each node only exposes its summary; pass includecontent: true for the FULL TEXT (re-read a document/handoff by topic without its LID) — then increase maxtokens, the content counts toward the budget.

When to use — To load a dense context on a subject before reasoning. Provides more context than noezissearch alone. includecontent: true to read the full text and not just the summaries.

noezis_report

On-demand thematic auto-documentation: assembles a human-readable Markdown report about a topic from what the graph already knows — decisions, knowledge passages, entities and contradictions on that topic. Deterministic (no LLM at read time); regenerable; thematic (unlike the chronological handoffs). Pure read.

When to use — To produce a readable synthesis of everything Noezis knows about a subject (knowledge-maintenance, briefing a human, onboarding a topic) — not a navigation, a finished document.

noezis_review_queue

Signal-driven review queue (KL-2): (1) non-decision knowledge (insight/preference/method/analysis) whose review window has elapsed (existing Pending lifecycle); (2) permanent decisions flagged by RECENT signals — a newer decision asserted on the same subject inside the window, or recurrent no_match searches mentioning the subject. Never age-based (a decision is superseded, not expired). Pure read.

When to use — To re-validate knowledge: what awaits review and which standing decisions show recent activity suggesting they may be outdated. The front-load shows terse counts; this verb gives the detail.

noezis_search

Semantic search in the Noezis knowledge graph. Returns 3-5 results with lid, score and summary directly included (include_text: true by default — no need for a second call to noezisnodesummary). Set include_text: false for a minimal payload. Prefer this tool over any other for documentary questions.

When to use — To find relevant documents from a natural-language question. Returns the text directly — no extra call needed to read the content.

noezis_since

Event cursor: everything that changed since an instant T — finished async jobs (ingest/recluster, done/failed), asserted decisions (including by other agents), detected tensions. Returns new_cursor to re-pass on the next call. Pure read, bounded.

When to use — At the start of a turn to catch up on what happened since the previous turn (job launched async, decision by another agent), without polling verb by verb.

noezis_status

Store indexation status: percentage of ready nodes, counters by state (ready/pending/indexing/failed), breakdown by node type, embedder mode. Call at the start of a session to check whether the corpus is well indexed before running searches.

When to use — Before a search, to check that documents are indexed (indexationpct > 0). Distinct from noezisdoctor (health/errors). With job_id: tracks an async ingestion job.

noezis_task_list

Lists Task nodes in the work ledger, optionally filtered by scope and/or status (open, claimed, in_progress, done, blocked).

When to use — To see pending or active tasks in a given workspace. Also surfaced automatically via open_tasks in the front-load context.

noezis_tools_summary

Aggregates the MCP catalog usage: for each tool, from the tool_invoked OpEvents, computes invocationcount, latencyp50ms, latencyp99ms, successrate and lastinvokedat. Optional filters: since/until (timestamp), session_id. Sorted by count DESC (tie-break name). Hard cap 200 tools (clamp). Pure read — no mutation.

When to use — To audit which tools are actually used, how often, with which latencies/success rates — detect the little-adopted or slow tools. Aggregated complement of noezis_op_history(action='tool_invoked').

noezis_triplets

Returns all SPO triplets (Subject-Predicate-Object) in the graph. Optional filters: predicate label (e.g. "uses"), subject/object name substring, minimum confidence. Sorted by decreasing confidence.

When to use — To query all relations of a given type across the graph (e.g. all 'uses' relations, all relations touching a given tech). Complement to noezis_relations (per-entity) with global scope.

Navigation — graph traversal

noezis_chains

All N-hop chains from an entity. Optional predicate filter. Depth filtering mandatory for depth > 2 (combinatorial explosion guard).

When to use — To explore all the N-hop connections from an entity, with or without a predicate filter.

noezis_children

Lists ALL the structural children of a node (exhaustive, not sampled). Use when you want to explore the full decomposition of a document or aggregate.

When to use — To go one level down in the hierarchy from a known LID.

noezis_community

All members of the topic clustering community containing the node. Use for an exhaustive panorama of a detected theme.

When to use — To get an exhaustive panorama of a thematic zone of the graph.

noezis_entity_neighbors

Returns the 1-hop neighboring entities via the typed relations. For each neighbor: the entity + the relation (predicate, confidence). Use after noezis_entities to explore the relations graph.

When to use — To explore the entities directly linked to a known entity.

noezis_explore_tree

Unified topological navigation: returns in one call the parent, the structural children, and the siblings (topic clustering neighbors) of a node. Replaces 2-3 separate calls (noezisparent + noezischildren + noezis_siblings). Ideal to quickly explore the neighborhood of a known LID.

When to use — To explore the immediate neighborhood of a known node in a single call. More efficient than 3 separate parent/children/siblings calls.

noezis_parent

Returns the direct structural parent of a node, or null for a root. Use to go up the hierarchy one level at a time.

When to use — To go up one level and get the enclosing context of a node.

noezis_path_between

A* path between two LIDs in the graph. Returns null if disconnected or max_hops reached. Use to explain how two documents are linked.

When to use — To explain how two nodes (known LIDs) are linked in the graph.

noezis_path_entities

A* path between two entities in the relations graph. Returns the shortest relation path (by weighted confidence). Note: the entity-relations layer is experimental and de-scoped from retrieval — result reliability depends on entity-extraction quality on your corpus.

When to use — To find how two entities are connected. E.g.: TechCorp → uses → Neo4j → has_flaw → CVE-XYZ.

noezis_relations

Returns an entity's typed relations — outgoing, incoming, or bidirectional. Optional filter by predicate_id.

When to use — To see all of an entity's relations (who uses it, what it is linked to, what it affects).

noezis_siblings

Neighbors of the node in its topic clustering community (semantic proximity). Use to discover thematically close documents without re-running a search.

When to use — To discover a node's immediate thematic neighbors (without a new search).

Write — mutations

noezis_assert_decision

Records a durable decision (ADR) in the graph. Blocks and returns a conflict if a contradictory decision already exists on the same subject — the agent must decide before continuing. Idempotent: re-asserting an identical decision returns kind: "duplicate".

When to use — To trace a durable architectural decision. Reserved for structuring choices that must be remembered across sessions.

noezis_capture_decision

Normalizes a statement into a triple (subject, predicate, value) and asserts it directly. Two modes: (1) arrow — statement = 'store_backend → surrealdb'; (2) explicit — provide subject + value (the statement serves as rationale). dry_run: true returns the normalized triple without commit. Non-blocking on contradiction: returns kind: "blocked" with the conflicting LID. Idempotent.

When to use — When the agent wants to capture a decision from a natural-language sentence or an arrow format, without manually building the SPV triple.

noezis_codify_corpus

Applies the batch codification on a set of already-indexed documents (without re-ingesting them). Three perimeters: explicit list, thematic community, or documents ingested since a date. Use dry_run: true to simulate without modifying the graph.

When to use — After adding or modifying a knowledge register, to update the codifications on the existing documents.

noezis_consolidate_knowledge

Merges or links nodes identified as similar/redundant. 'merge' strategy: creates a new aggregated node with the merged summary. 'link' strategy: lays Inferred edges between the nodes (less destructive). Emits an OpEvent for traceability. Use sparingly.

When to use — After detecting duplicated or overly fragmented nodes. Prefer 'link' if unsure — 'merge' is irreversible.

noezis_doc_update

Updates a section or a documentation file on disk, re-ingests the file into the graph, and emits a doc_updated OpEvent for traceability. Can target a specific H2/H3 section or the whole file. Composed: write + ingest + OpEvent in a single atomic operation.

When to use — To update a doc file (.md, .rs, etc.) and trace why this change was made. Use before proposing a direct edit so the graph stays in sync with the repo.

noezis_ingest

Ingests a document into the graph. Source: exactly ONE of the fields text, path or url. The deterministic validation pipeline pipeline validates 5/5 or rolls back. Use to memorize a text, a local file or (V2) a URL.

When to use — To add a new document (text or local file) to the graph, after checking for absence.

noezis_ingest_batch

Ingests up to 50 documents in a single MCP call. Each item is identical to an individual noezis_ingest call (text or path). The items are processed in parallel on the server side. Indispensable to bootstrap a corpus without multiplying round-trips.

When to use — To ingest N texts or files in a single tool call. Use when you have a list of documents to index (N > 1).

noezis_prefs_drop

Drops a preference (moves it to Dormant). The preference is preserved for audit but is no longer injected at front-load.

When to use — When the user wants to remove a preference that was inferred incorrectly.

noezis_prefs_pin

Pins a preference — prevents the autonomous loop from reverting it to Dormant. Use for preferences you explicitly want to lock in.

When to use — When the user explicitly wants to lock in a preference that was promoted automatically.

noezis_purge_node

PERMANENTLY deletes a node from the graph by its LID (+ its child passages if it is a Document; the edges are cascaded). Emits a purged OpEvent. Refuses the protected founding documents (CLAUDE.md, CONTEXT.md, ROADMAP.md, etc.). Usage: clean up a test pollution or an erroneous node. Irreversible — no dry-run.

When to use — To remove a parasitic node (test transcript, erroneous doc) without re-indexing the whole store or stopping the daemon.

noezis_recluster

Rebuilds the store's hierarchical tree: clusters all the Ready passages by topic clustering and materializes multi-level AggregateNodes (topic centers = mean of the children), with inter-aggregate Proximity edges and community summaries (SLM naming if the model is present, otherwise a deterministic label). GLOBAL and idempotent pass: first purges the aggregates of the previous run. Costly — to launch after a large ingestion, not on each addition. ASYNC by default: returns { jobid, status } immediately; track via noezisstatus({ job_id }).

When to use — After a substantial ingestion, to (re)build the hierarchical navigation tree over the whole store.

noezis_resolve_tension

Resolves a detected tension (EdgeKind::Tension) with a mandatory rationale and a canonical resolution code: accepteda | acceptedb | merged | deferred | invalidated. Mutates the resolution None → Some() and emits an idempotent TENSIONRESOLVED OpEvent. Idempotent: a second call with an identical (tensionlid, resolutioncode) returns kind: "already_resolved" without a new OpEvent. If the tension is already resolved with another code → kind: "conflicting_resolution" (JSON-RPC success, typed business refusal). Typed errors in INVALIDPARAMS: invalidlid, unknowntension, notatension, invalidresolutioncode, emptyrationale, invalid_actor.

When to use — To close an active tension after human review — typically after listing the tensions via noezislisttensions.

noezis_retract_decision

Retracts a decision: sets it to the reversible Retracted state with a mandatory reason, withdrawing it from every live surface (front-load, search, review queue, contradiction audit). Unlike supersede, no replacement is needed. The audit is preserved (the node survives until store gc); the retracted key no longer blocks a fresh assertion. Idempotent on an already-retracted decision.

When to use — To cancel a mistaken or obsolete ADR that has NO replacement (wrong repo/subject, abandoned choice). If a newer decision replaces it, use noezis_supersede instead. Always provide an explicit reason (never auto-generated).

noezis_subscribe_node

Subscribes to the STALE/UPDATED events of a LID. The server will then emit notifications/noezis/stale JSON-RPC notifications. Use to stay notified that an indexed document changed.

When to use — To be notified when a given node becomes stale or is updated.

noezis_supersede

Marks a decision as superseded (replaced) by another. Creates the deprecation link and traces the event in the journal. Idempotent. Refuses if the decision to deprecate is already replaced by a third one — then returns the conflict for arbitration.

When to use — To retract an existing ADR in favor of a more recent decision. Always provide an explicit justification (never auto-generated).

noezis_task_claim

Atomically claims an open Task (compare-and-set). Sets status to 'claimed' and records holder + optional TTL. Returns claimed=false if the task was already taken.

When to use — Before starting work on a task, to prevent two agents from working on the same item concurrently.

noezis_task_create

Creates a new Task node in the shared work ledger (A2). Tasks represent units of work shared across sessions and agents. Scope = logical workspace (e.g. repo name, branch, or session id).

When to use — To record a new task or work item that spans sessions or needs to be picked up by another agent.

noezis_task_update

Updates the status (and optionally notes) of a Task. Valid transitions: open → claimed → in_progress → done | blocked.

When to use — To mark a task as in_progress, done, or blocked after claiming it.

noezis_watch_folder

Main entry point to initialize or sync a repo. Call with the repo's root path to (1) immediately ingest all the existing files in a batch and (2) watch for future modifications via incremental SUPERSEDEDBY re-ingestion. This is the first call to make in a not-yet-indexed repo — a single call suffices, no need to ingest the files one by one. ASYNC by default: returns { jobid, status } immediately; track via noezisstatus({ jobid }).

When to use — To initialize a repo's index (first call) or resynchronize after an interruption. Prefer this tool over noezis_ingest repeated on each file.