MCP · 12. Tool reference, part 1

This is the complete contract for the first 70 of the daemon's 118 MCP tools, grouped exactly as the code groups them. The remaining 49, coordination, GitHub, substrate, features, traces, approvals, orchestrators and punchcards, are in chapter 13. Nothing has been summarised away.

This chapter is reference. For how the catalogue is filtered, what token_budget does when omitted, and what the four JSON-RPC methods are, read chapter 11 first.

12.0 How to read these tables

Grouping follows the section banners in crates/crux-mcp/src/tools/mod.rs, which is also the order list_tools_with_flags() emits.

Column	Meaning
Definition	Line in crates/crux-mcp/src/tools/mod.rs where the ToolDefinition literal starts
Handler	The arm call_tool() dispatches to (mod.rs:2881 onward)
Surface	[local] or [hosted], from marker_for_tool (tool_surface.rs:215). Only three tools are [hosted]; everything else defaults [local] (tool_surface.rs:212)
token_budget	required means it is in the schema's required[] and the call fails without it. default N means it is optional and silently defaults. unbounded means it is accepted and does not bound the result. - means the schema has no such parameter
Flag	The environment variable gating the tool, with its default. - means always on

Capability. Unless a group says otherwise, the RCX capability string for a tool is crux-mcp.<tool_name> (mod.rs:2713). The one exception in this chapter is retrieval, 12.5. Where a tool is a loopback proxy onto the daemon's own HTTP API, the HTTP scope it presents is named in the group's preamble.

Envelope. Every response is additionally wrapped in the standard MCP {"content": [{"type":"text", …}]} envelope. The "Output" lines below describe what is inside it, and reproduce tool_output_docs() (mod.rs:2728), the canonical machine-readable output contract, also served through get_bootstrap(topic="tool-output").

Flag parsing is not uniform. Six incompatible dialects decide what counts as "on". FLAG=yes enables one tool and disables another. Before setting anything in the Flag column, read chapter 15, section 15.1.

12.1 Session handshake

Tool	Definition	Handler	Surface	token_budget	Flag
cuecrux_session	mod.rs:163	cuecrux_session.rs:62	[local]	-	,

Opens a CueCrux session and returns a typed capability plan covering retrieval, proofing, memory, journaling and audit, for both local and hosted deployments.

It is listed first on purpose (mod.rs:125), and every other tool's description carries a pointer back to it via CUECRUX_SESSION_HINT (mod.rs:119, appended at :2454).

Schema, cuecrux_session.rs:32. additionalProperties: false at both levels.

Param	Type	Required	Default	Constraints
intent	string	no	-	Free text. Recorded per-passport and re-read by the next tools/list for dynamic surface shaping. Only five values carry weight, see 11.10
hints	object	no	-	additionalProperties: false
hints.prefer_bulk	boolean	no	-
hints.max_capabilities	integer	no	-	minimum: 0
hints.want_parent_chain	boolean	no	-
hints.hide_exclusions	boolean	no	false	Suppresses the capability graph's excluded list

Output: a SessionPlan of plan_id, session_id, passport, channels (bulk optional, mcp), capability_graph[], receipt (hash, signature optional, signer_kid optional, mode), budget, minted_at, session_ttl_s.

Side effect: calls passport::auto_issue_if_mapped(ctx) first, idempotent, and a no-op when CORECRUXD_AGENT_PASSPORTS is off or the agent is unmapped. Requires ctx.daemon_base_url; returns INTERNAL_ERROR if the MCP server was not wired to corecruxd.

12.2 Autonomy contract

Tool	Definition	Handler	Surface	token_budget	Flag
autonomy_contract	mod.rs:169	autonomy.rs:244	[local]	unbounded	CORECRUXD_FEATURE_AUTONOMY_CONTRACT, default off

Returns the calling passport's per-tool {allowed, scope, cost_credits, why_denied?} matrix against the current RCX capability token. Metadata only; it reads no memories.

Schema, autonomy.rs:67. additionalProperties: false.

Param	Type	Required	Default	Constraints
token_budget	integer	no	-	minimum: 1. Approximate, and ignored when 0. Omitted means no trim, the full matrix is returned (autonomy.rs:218)

Output: {feature_enabled, passport_id, tier, token_id, token_hash, capabilities: [{name, allowed, scope, backend_id, mode, cost_credits, why_denied?}], summary: {total_tools, returned, allowed, denied, truncated_by_token_budget}}. With the flag off: feature_enabled: false and an empty capabilities.

Passport-attributed: it reflects only the calling passport. You cannot enumerate another's. Reserved-prefix tools come back allowed: false with why_denied: "reserved-prefix tool" for non-operator callers.

12.3 Reuse check

Tool	Definition	Handler	Surface	token_budget	Flag
reuse_check	mod.rs:175	reuse.rs:55	[local]	-	CORECRUXD_FEATURE_REUSE_CHECK, default off

"Does this already exist?", ranked reuse candidates for a one-line description of what you are about to build, fused from the tenant retrieval index and the Features lens.

Param	Type	Required	Default	Constraints
tenant_id	string	yes	-	Tenant for the scoped search
description	string	yes	-	One line: what you are about to build
limit	integer	no	5	Maximum candidates per source
min_score	number	no	-	Minimum relevance threshold

Output: {schema, verdict, retrieval_candidates: [{result_id, rank, score, doc_length_tokens}], capability_candidates: [{id, name, system, maturity, files, overlap_terms}], guidance} where verdict is reuse-candidate-found or nothing-found. With the flag off: CAPABILITY_DENIED (reuse.rs:47).

Note the asymmetry: this tool has no token_budget despite being a retrieval fan-out. Bounding is via limit only.

12.4 Engrams: pre-execution overlays

Tool	Definition	Handler	Surface	token_budget	Flag
engram_resolve	mod.rs:199	engrams.rs:53	[local]	-	CORECRUXD_FEATURE_ENGRAM_MCP, default off

Resolves pre-execution behavioural overlays from the local catalog. Two modes: omit names for the content-free manifest, which is the session-discovery path; pass names for full content when the caller's capability class allows it.

Param	Type	Required	Default	Constraints
names	array<string>	no	-	name@version entries, maximum 20. Omit for manifest mode
model_id	string	no	-	Caller model id; derives the capability class (fast, capable, frontier)
intent_bucket	string	no	-	Filter to one intent bucket
tenant_id	string	no	local

Output, manifest mode: {schema, capability_class, engram_manifest}. Resolve mode: {schema, capability_class, engrams: [{name, version, intent_bucket, content, prompt_hash, applicable_why}], engram_set_hash, manifest_hash}. With the flag off: CAPABILITY_DENIED.

12.5 Retrieval

Tool	Definition	Handler	Surface	token_budget	Flag
query	mod.rs:223	query.rs:22	[local]	unbounded	-
query_scan	mod.rs:245	query.rs:174	[local]	not in schema	-
query_expand	mod.rs:264	query.rs:257	[local]	-	,

Capability: all three share corecrux.query.local, not crux-mcp.<name>, the one special case in rcx_capability_for_tool (mod.rs:2717). A grant of one is a grant of all three.

Omitting token_budget on query returns unbounded results (query.rs:120). There is no default and no clamp. See 11.11.

query

Lexical and graph fusion. Returns scored results with query coverage.

Param	Type	Required	Default	Constraints
tenant_id	string	yes	-
query	string	yes	-	Natural-language query
limit	integer	no	10
token_budget	integer	no	-	"Optional token budget for result trimming". Omitted means no trimming at all
min_score	number	no	-

Output: {results: [{doc_id, score, segment_index, token_count}], coverage: {score, gaps, below_floor}, meta: {backend, took_ms, segments_searched}}.

query_scan

Metadata-only scan, no content. Use it to decide what to expand.

Param	Type	Required	Default
tenant_id	string	yes	-
query	string	yes	-
limit	integer	no	20

Output: {results: [{doc_id, score, token_count}], meta: {took_ms, segments_searched}}, plus tokens_returned and budget_truncated (query.rs:227).

No token_budget parameter exists in this tool's schema. The handler reads one if it is passed (query.rs:202), so passing it works and is not an error, but no schema advertises it, and omitting it applies no trim.

query_expand

Expands prior result ids to full content.

Param	Type	Required	Default
tenant_id	string	yes	-
result_ids	array<string>	yes	-

Output: {results: [{doc_id, content, token_count}]}. Also no token_budget.

All four retrieval-shaped tools, the three above plus query_facts, advertise the CRC-v1 output contract via x-crux-output-schema (crc_v1.rs:380).

12.6 Facts

Tool	Definition	Handler	Surface	token_budget	Flag
store_fact	mod.rs:286	facts.rs:113	[local]	-	,
query_facts	mod.rs:317	facts.rs:422	[local]	unbounded	-
delete_fact	mod.rs:347	facts.rs:615	[local]	-	,
list_entities	mod.rs:361	facts.rs:651	[local]	-	,
get_bootstrap	mod.rs:372	facts.rs:829	[local]	-	,
fact_history	mod.rs:398	facts.rs:375	[local]	-	,

store_fact

Writes one fact.

Param	Type	Required	Default	Constraints
entity	string	yes	-
key	string	yes	-
value	string	yes	-
source_receipt	string	no	-	CROWN receipt reference
confidence	number	no	1.0	0 to 1
private	boolean	no	false	Scopes the fact to the calling agent under an __agent::<name>:: prefix
horizon_class	string	no	-	One of volatile, medium, stable, none. Omit for the entity-prefix default
freshness_horizon	string	no	-	Free-text horizon line, parsed to a horizon_class when horizon_class is omitted
supersedes	array<string>	no	-	fact_ids this write explicitly retires, across entities. Each must exist and be visible to the caller, else the call is rejected. Reversible

Output: {fact_id, entity, key, version, superseded_fact_ids: [string]}.

query_facts

Ranked by effective confidence: a fact past its freshness horizon is demoted to half its stored confidence for ranking only, a binary stale-demotion, not a continuous decay curve. Stored confidence is never mutated. Emits the audit envelope when CORECRUXD_FEATURE_AUDIT_ENVELOPE is on.

Param	Type	Required	Default	Constraints
query	string	no	-	Keyword search across values, keys and entities
entity	string	no	-	Filter to one entity, exact match
top_k	integer	no	10
token_budget	integer	no	-	Omitted means the whole top_k is returned untrimmed
include_superseded	boolean	no	false	When true, retired facts are returned and superseded_by is exposed
as_of	string	no	-	RFC 3339 bi-temporal filter: facts whose valid-time interval contains the instant, regardless of when they were learned
min_effective_confidence	number	no	-	Floor from 0 to 1 on recall-time effective confidence. structuredContent.filtered_below_threshold distinguishes "no facts" from "nothing above the floor"

Output: {rows: [{fact_id, entity, key, value, confidence, effective_confidence, horizon_class, freshness, age_hours, superseded_by?}]}.

The schema has no required[] array at all, every parameter is optional, so a bare {} is a valid full-store scan.

There is no entity_prefix parameter and no key parameter. Both are silently dropped if passed; the handler hardcodes entity_prefix: None (facts.rs:487). An unfiltered top-10 comes back and reads like an answer. This is drift item 1 in chapter 15.

delete_fact

Soft delete; the receipt is preserved.

Param	Type	Required
fact_id	string	yes

Output: {deleted, fact_id}.

list_entities

No parameters, the schema declares properties: {}.

Output: {entities: [string]}, sorted, deduplicated, entities holding at least one active fact.

get_bootstrap

Queries bootstrap knowledge under the __bootstrap__:: entity prefix. Topic taxonomy and content sources are in 11.12.

Param	Type	Required	Default	Constraints
topic	string	no	-	Normalised at facts.rs:882. doc and docs become doc; pattern and patterns become pattern; error, errors, resolution, resolutions become resolution; tool, tool-output, tool-outputs become tool-output. Anything else passes through verbatim
query	string	no	-	Narrowing search term

Output: {facts: [{entity, key, value}], total_tokens}, rendered one line per fact as [entity] key = value (facts.rs:854).

There is no token_budget parameter (mod.rs:378); the handler hardcodes top_k: 100, token_budget: None (facts.rs:844). Passing one is ignored, not rejected. This is drift item 3 in chapter 15.

fact_history

Full version chain for one (entity, key) pair.

Param	Type	Required
entity	string	yes
key	string	yes

Output: {versions: [{fact_id, value, version, supersedes, confidence, stored_at, deleted}]}.

12.7 Acknowledged memory use

Tool	Definition	Handler	Surface	token_budget	Flag
memory_acknowledge_use	mod.rs:416	memory_use.rs:119	[local]	-	CORECRUXD_FEATURE_MEMORY_ACK, default off

Declares which stored fact ids were consulted while producing the current turn, so a host can render "I used this" annotations. Requires an authenticated passport. Emits the audit envelope.

Param	Type	Required	Default	Constraints
turn_id	string	yes	-	Opaque per-host turn identifier
fact_ids	array<string>	no	-	Fact ids consulted. Reserved-prefix entries (__agent::, __ops::, __bootstrap__::) are stripped
intent	string	no	answer	One of answer, decision, tool_call, implicit, documented in the description, not enforced as a JSON-Schema enum
retrieved_chunk_ids	array<string>	no	-	Paid tier only; ignored on the free tier
confidence	number	no	-	0 to 1
note	string	no	-

Output: {turn_id, intent, feature_enabled, receipt_ref, memories_used: [{fact_id, topic, age_days}], filtered_count, redacted_count, not_found_count, not_visible_count}.

12.8 Verifiable output receipts

Tool	Definition	Handler	Surface	token_budget	Flag
output_attest	mod.rs:453	output_attest.rs:236	[local]	admission gate	CORECRUXD_FEATURE_C2PA_OUTPUT, default off

Binds a produced artefact to a CROWN receipt as a C2PA manifest. Reuses the daemon's existing Ed25519 CROWN signer, no new key class. Verifiable offline via corecruxctl output-verify and online at /v1/output/verify.

Param	Type	Required	Default	Constraints
content_bytes_base64	string	see note	-	Base64 content
content_path	string	see note	-	Local path the daemon reads
content_type	string	no	-	MIME type
receipt_id	string	yes	-	The CROWN receipt this artefact binds to
claim_generator	string	no	cuecrux/<version>
token_budget	integer	no	-	Soft cap on content size in tokens, roughly bytes divided by 4

Note: one of content_bytes_base64 or content_path is required in practice, but the schema's required[] lists only receipt_id. Supplying neither fails in the handler, not in schema validation.

token_budget here is an admission gate, not a trimmer (output_attest.rs:285): content larger than the budget is rejected with -32602 and the message content size N bytes (~M tokens) exceeds token_budget B. Omitting it means no size gate.

Output: {content, manifest: {manifest_id, spec_version, manifest_jumbf_base64, content_hash_blake3_hex, crown_receipt_id, signer_key_id, signer_passport, verify_url, verify_command, ai_act_notice}}.

Signer mode has its own flag, CORECRUXD_FEATURE_C2PA_X509_SIGNER, default off (output_attest.rs:72), together with CORECRUXD_C2PA_SIGNER_BACKEND, _KEY_ID and _SIGNING_KEY_B64.

12.9 Scoped forget

Tool	Definition	Handler	Surface	token_budget	Flag
memory_forget	mod.rs:480	forget.rs:381	[local]	unbounded	CORECRUXD_FEATURE_SCOPED_FORGET, default ON
memory_forget_dry_run	mod.rs:514	forget.rs:316	[local]	unbounded	none, always available

The dry-run tool is explicitly not flag-gated: "Always available, does not require the feature flag" (mod.rs:518). Preview before you erase.

memory_forget's own catalogue description is wrong about its own flag. The description at mod.rs:484 states the tool "requires … feature flag CORECRUXD_FEATURE_SCOPED_FORGET=1", implying default-off. The code defaults it ON, forget.rs:76 ends .unwrap_or(true). An operator reading the tool description will believe a live erasure tool is disabled. Trust the code. Full disclosure in chapter 15.

The parser is strict (v == "1" || v.eq_ignore_ascii_case("true")), so setting the flag to yes or on disables the tool. CORECRUXD_FEATURE_SCOPED_FORGET=0 is the correct way to disable it.

Recovery window: CORECRUXD_FORGET_RECOVERY_WINDOW_DAYS, default 7, minimum 1 (forget.rs:79).

memory_forget

Param	Type	Required	Default	Constraints
scope	object	yes	-	Typed selector, oneOf five shapes, each requiring type and value: entity_prefix, key_glob, passport_id, before_timestamp (a date-time value), tenant_id
reason	string	yes	-	Audit-record requirement
tenant_id	string	no	default	The tenant the receipt is attributed to
token_budget	integer	no	-	Caps the number of facts the resolver touches. Omitted means the resolver touches everything in scope

Output: {content, forget_receipt_id, facts_affected, recovery_window_seconds, recovery_window_ends_at, receipt_body_cbor_hex, receipt_body_hash_hex, scope, passport_id}. Soft-deletes, filters reserved prefixes, and emits a signed Forget receipt naming the initiating passport.

memory_forget_dry_run

Param	Type	Required	Default	Constraints
scope	object	yes	-	The same typed scope, but the dry-run schema declares it only as {"type":"object"} with no oneOf mirror
token_budget	integer	no	-	No description in the schema. Omitted means unbounded

Output: {content, scope, count, facts_that_would_be_affected: [{fact_id, entity, key, stored_at, tokens}], dry_run: true}. Excludes __agent::, __ops::, __bootstrap__:: and __agent_session::.

12.10 Memory panel

Tool	Definition	Handler	Surface	token_budget	Flag
memory_view	mod.rs:539	memory.rs:155	[local]	default 2000	CORECRUXD_FEATURE_MEMORY_PANEL, default on; =0 disables
memory_edit	mod.rs:562	memory.rs:310	[local]	-	same
memory_pin	mod.rs:584	memory.rs:443	[local]	-	same
memory_history	mod.rs:604	memory.rs:518	[local]	-	same

memory_view

Paginated, narrative-friendly consumer read. Filters __agent::, __ops::, __bootstrap__:: and __memory_pin::.

Param	Type	Required	Default
entity	string	no	-
key	string	no	-
top_k	integer	no	20
token_budget	integer	no	2000, applied at memory.rs:170, documented in the description only, not as a schema default key

Output: {content, structuredContent: {facts: [{id, entity, key, value, version, stored_at, confidence, pinned, source_receipt}], total_tokens, returned}}.

memory_edit

Creates a new version superseding the prior fact. Requires an authenticated identity. Reserved-prefix entities are refused.

Param	Type	Required
fact_id	string	yes
new_value	string	yes
reason	string	no, embedded as memory_edit:<reason> in the new fact's source_receipt

Output: {content, structuredContent: {old_fact_id, new_fact, reason}}.

memory_pin

Pinned facts survive decay and scoped forget. Pin state is per-agent under the reserved __memory_pin::<agent>:: entity, so it never leaks across agents.

Param	Type	Required	Default
fact_id	string	yes	-
pinned	boolean	no	true

Output: {content, structuredContent: {fact_id, pinned}}.

memory_history

Accepts either {entity, key} or {fact_id}. The schema has no required[]. Reserved prefixes are refused, use the operator-side fact_history for those.

Param	Type	Required
entity	string	no
key	string	no
fact_id	string	no

Output: {content, structuredContent: {versions: [{id, value, version, stored_at, supersedes, deleted, source_receipt}]}}.

12.11 Freshness and decay

Tool	Definition	Handler	Surface	token_budget	Flag
memory_freshness	mod.rs:625	freshness.rs:97	[local]	default 500	CORECRUXD_FEATURE_FRESHNESS, default on; =0 disables
memory_sweep_candidates	mod.rs:647	freshness.rs:184	[local]	default 500	same
memory_set_horizon	mod.rs:723	freshness.rs:348	[local]	-	same
memory_reverify	mod.rs:743	freshness.rs:407	[local]	-	same

With the flag off, all four return CAPABILITY_DENIED (freshness.rs:68).

memory_freshness

Per-fact decay state. Read-only. Emits the audit envelope.

Param	Type	Required	Default
entity	string	no	-
key	string	no	-
top_k	integer	no	20
token_budget	integer	no	500 (declared in the schema at mod.rs:638)

Output: {rows: [{fact_id, entity, key, horizon_class, freshness, age_hours, stored_at, reverified_at?}], policy: {volatile_stale_hours, medium_stale_days, stable_stale_days}, now}. freshness is fresh, stale or unknown.

memory_sweep_candidates

Read-only janitor: facts that are stale or explicitly superseded. Non-mutating.

Param	Type	Required	Default
top_k	integer	no	50
token_budget	integer	no	500 (declared at mod.rs:661)

Output: {content, structuredContent: {rows: [{fact_id, entity, key, reason, freshness, horizon_class, age_hours, superseded_by?, stored_at}], dry_run: true, now}}. reason is stale, superseded or stale+superseded.

memory_set_horizon

Requires an authenticated passport. Reserved-prefix facts cannot be re-classified here.

Param	Type	Required	Constraints
fact_id	string	yes	Form f_…
horizon_class	string	yes	One of volatile, medium, stable, none

Output: {fact_id, horizon_class, ok}.

memory_reverify

Re-anchors the decay clock without rewriting the value, and records a CROWN-verifiable Reverify receipt under __reverify_receipts__::<fact_id>. Requires an authenticated passport.

Param	Type	Required
fact_id	string	yes

Output: {fact_id, receipt_id, receipt_class: 'Reverify', reverified_at}.

12.12 Contradiction surfacing and safe consolidation

Tool	Definition	Handler	Surface	token_budget	Flag
memory_contradictions	mod.rs:671	consolidation.rs:90	[local]	default 500	CORECRUXD_FEATURE_CONSOLIDATION, default on; =0 disables
memory_consolidate	mod.rs:693	consolidation.rs:155	[local]	-	same

memory_contradictions

Read-only detection of active, non-superseded facts that share an (entity, key) but carry opposite deterministic polarity, enabled against disabled, active against inactive. It detects and surfaces only. It never resolves.

Param	Type	Required	Default
limit	integer	no	50
token_budget	integer	no	500 (declared at mod.rs:684)

Output: {content, structuredContent: {candidates: [{entity, key, reason, polarity_a, polarity_b, fact_ids: [string], values: [string]}], count, limit, dry_run: true}}.

memory_consolidate

An explicit write: collapse named targets under one (entity, key) into a canonical fact, superseding the targets with history preserved, and emitting a consolidation receipt. Requires an authenticated passport.

Param	Type	Required	Default	Constraints
entity	string	yes	-	Shared by all targets and the canonical fact
key	string	yes	-	Shared by all targets and the canonical fact
canonical_value	string	yes	-	The surviving value
target_fact_ids	array<string>	yes	-	Non-empty. Each must be in (entity, key) and unprotected
protected_fact_ids	array<string>	no	-	Caller-pinned ids. If any appears in target_fact_ids the call is rejected
confidence	number	no	1.0	For the canonical fact
protected_confidence_floor	number	no	0.99	Targets at or above the floor are refused
consolidation_id	string	no	auto	Stable receipt id
horizon_class	string	no	-	One of volatile, medium, stable, none

Output: {content, structuredContent: {status: 'consolidated', receipt: {consolidation_id, canonical_fact_id, superseded_fact_ids: [string], source_fact_ids: [string]}}}.

Refuses protected targets, pinned, receipt-linked, private or high-confidence, with CAPABILITY_DENIED and a reason.

12.13 Artefacts: deferred output parking

Tool	Definition	Handler	Surface	token_budget	Flag
artefact_put	mod.rs:763	artefacts.rs:141	[local]	unbounded	CORECRUXD_FEATURE_ARTEFACTS, default off
artefact_get	mod.rs:787	artefacts.rs:196	[local]	unbounded	same
artefact_list	mod.rs:807	artefacts.rs:246	[local]	unbounded	same

All three describe token_budget as "Mandatory output-token cap (QC.2)" and none of them list it in required[], and none validate it. The prose is wrong; the schema is the contract. Sources: mod.rs:778, :798, :819.

artefact_put

Content-addressed with BLAKE3: identical bytes always produce the same id. Requires an authenticated passport.

Param	Type	Required	Default	Constraints
content_bytes_base64	string	yes	-	Base64 content
mime_type	string	yes	-	Free-form MIME label
tool_origin	string	no	-	Which tool produced this; surfaced in artefact_list
ttl_seconds	integer	no	7 days	Maximum 90 days. 0 means no expiry
token_budget	integer	no	-	Not validated

Output: {content, structuredContent: {artefact_id, mime_type, tool_origin, size_bytes, created_at, expires_at}}. Ids take the form art_<blake3_hex>.

artefact_get

Param	Type	Required
artefact_id	string	yes
token_budget	integer	no

Output: {content, structuredContent: {artefact_id, mime_type, tool_origin, size_bytes, created_at, expires_at, content_base64}}.

Cross-passport reads return CAPABILITY_DENIED, deliberately, so the operator can audit the attempt.

artefact_list

Passport-scoped, newest first. Emits the audit envelope, surfacing parked artefact ids as memories_used[].

Param	Type	Required	Default
top_k	integer	no	20
scope	string	no	, Substring filter on mime_type or tool_origin
token_budget	integer	no	-

Output: {content, structuredContent: {artefacts: [{artefact_id, mime_type, tool_origin, size_bytes, created_at, expires_at}], count}}. Reserved-prefix mime entries are filtered; cross-passport entries are never included.

12.14 Sessions

Tool	Definition	Handler	Surface	token_budget	Flag
get_session	mod.rs:829	sessions.rs:16	[local]	-	,
save_session	mod.rs:845	sessions.rs:39	[local]	-	,
session_checkpoint	mod.rs:881	sessions.rs:77	[local]	required	-
list_sessions	mod.rs:907	sessions.rs:130	[local]	-	,
delete_session	mod.rs:918	sessions.rs:153	[local]	-	,
archive_session	mod.rs:932	sessions.rs:183	[local]	-	,
unarchive_session	mod.rs:947	sessions.rs:188	[local]	-	,

Sessions are namespaced per agent via scoped_session_id, becoming __agent_session::<agent>::<id> (scope.rs:124). Anonymous callers get the raw id.

get_session

Param	Type	Required
session_id	string	yes

Output: {session_id, state, updated_at, total_tokens}.

save_session

Param	Type	Required	Constraints
session_id	string	yes
state	object	yes	Arbitrary JSON. Two conventional optional keys are read by the console and every session lens: state.title, a short human name, and state.summary, one paragraph. Both plain strings, both optional. Absent means the console falls back to decisions[0], then note, then context_summary, then summary, then a short id, and labels the row untitled. Everything else is opaque and preserved verbatim
ttl_seconds	integer	no	The session expires after this duration

Output: {session_id, updated_at}. Writer identity is stamped automatically; there is no argument for it, and anonymous callers store no identity rather than a guessed one.

session_checkpoint

The only session tool that requires token_budget. Stores a compact crux.session_checkpoint.v1 state scoped to the calling agent.

Param	Type	Required	Constraints
session_id	string	yes
token_budget	integer	yes	Must be greater than 0. Omitting it fails with -32602
objective	string	no
current_milestone	string	no
decisions	array	no	items: {}, untyped elements
open_questions	array	no	items: {}
files_touched	array<string>	no
commands_run	array<string>	no
test_status	any	no	The schema declares only a description, no type
next_action	string	no
ttl_seconds	integer	no

Output: {content, structuredContent: {session_id, updated_at, total_tokens}}.

list_sessions

Param	Type	Required	Default
include_archived	boolean	no	false

Output: {sessions: [string]}, sorted.

There is no prefix or pattern filter. include_archived is the only parameter (mod.rs:909). Passing anything else is silently ignored and you get every visible session. This is drift item 6 in chapter 15.

delete_session

Destructive. Prefer archive_session.

Param	Type	Required
session_id	string	yes

Output: {deleted, session_id}.

archive_session

Soft and reversible: state is preserved in full and hidden from the default list_sessions view.

Param	Type	Required
session_id	string	yes
reason	string	no

unarchive_session

Restores a session to the default listing.

Param	Type	Required
session_id	string	yes

12.15 Hardening and audit posture

Tool	Definition	Handler	Surface	token_budget	Flag
route_access_matrix	mod.rs:961	hardening.rs:78	[local]	-	,
execplan_gate	mod.rs:971	hardening.rs:14	[local]	required	-
auth_posture_audit	mod.rs:993	hardening.rs:127	[local]	-	,
egress_policy_check	mod.rs:1003	hardening.rs:150	[local]	-	,

route_access_matrix

No parameters. Returns the static high-risk HTTP route gate matrix.

Output: {content, structuredContent: {routes: [{route, required_any_scope: [string], passport_binding, tenant_binding, notes}]}}.

execplan_gate

Records a milestone gate as a stable fact under entity execplan:<slug>, key gate:<milestone>.

Param	Type	Required	Constraints
slug	string	yes	ExecPlan slug without the execplan: prefix
milestone	string	yes	For example M2 or gate:M2
status	string	yes	One of passed, failed, blocked, skipped
commit_sha	string	yes
token_budget	integer	yes	Must be greater than 0
tests_passing	boolean	no
artifacts	array<string>	no	Files, logs, PR links
notes	string	no

Output: {content, structuredContent: {fact_id, entity, key, commit_sha, status}}.

auth_posture_audit

No parameters.

Output: {content, structuredContent: {schema: 'crux.auth_posture_audit.v1', checked_at, mcp_agent, daemon_loopback_configured, rcx_router_configured, agent_passports_enabled, data_dir_configured, notes: [string], recommended_checks: [string]}}.

HTTP auth mode is deliberately not exposed through MCP. If you need it, read it on the daemon.

egress_policy_check

Param	Type	Required	Default
target	string	yes	-
purpose	string	no	-
allow_loopback_http	boolean	no	true
allow_plain_http	boolean	no	false

Output: {content, structuredContent: {schema: 'crux.egress_policy_check.v1', target, purpose, allowed, scheme, host, reasons: [string]}}. Policy: HTTPS is allowed; plain HTTP only for loopback, or under an explicit allow_plain_http.

12.16 Observability

Tool	Definition	Handler	Surface	token_budget	Flag
get_gaps	mod.rs:1023	observe.rs:22	[local]	-	,

Sourced from the ops observation layer. Check it after a low-coverage query.

Param	Type	Required
query	string	no, keyword filter for gap descriptions

Output: {gaps: [{entity, key, value, stored_at}], total_tokens}.

There is no GET /v1/gaps HTTP route. This MCP tool, or GET /v1/features/capabilities/analysis/gaps, is the real surface. Drift item 2 in chapter 15.

12.17 Session observations

Tool	Definition	Handler	Surface	token_budget	Flag
list_observations	mod.rs:1041	observations.rs:334	[local]	-	CORECRUXD_OBSERVE, default off (daemon-side)
get_observation	mod.rs:1063	observations.rs:385	[local]	-	same
verify_observation	mod.rs:1078	observations.rs:416	[local]	-	same

Multi-provider capture. Each record carries an Ed25519 receipt verifiable against the daemon's published passport public key. The gate is daemon-side: CORECRUXD_OBSERVE (agentgraph_kinds.rs:139), route class at route_auth.rs:514.

list_observations

Param	Type	Required	Default	Constraints
session_id	string	yes	-
since	string	no	-	RFC 3339 lower bound on the observation timestamp
provider	string	no	-	claude-code, openai, anthropic, codex-cli, openclaw, documented, not schema-enforced
limit	integer	no	50	Maximum 500

Output: {session_id, count, observations: [{observation_id, session_id, ts, provider, principal, kind, payload, receipt: {alg, signed_by, body_hash, signature}}]}.

get_observation

Param	Type	Required
session_id	string	yes
observation_id	string	yes

Output: a single observation record, or a not-found text response.

verify_observation

Re-canonicalises the record, recomputes the BLAKE3 body hash and verifies the Ed25519 signature.

Param	Type	Required
session_id	string	yes
observation_id	string	yes

Output: {observation_id, ok, hash_match, signature_valid, recomputed_hash, receipt_hash, reason?}.

12.18 Receipt verification

Tool	Definition	Handler	Surface	token_budget	Flag
receipt_verify	mod.rs:1097	receipt_verify.rs:96	[local]	-	CORECRUXD_FEATURE_RECEIPT_VERIFY, default off

Loopback scope: receipts:read (receipt_verify.rs:45). Requires an authenticated agent identity, the audit pattern is that only the signer or an operator re-verifies.

Param	Type	Required	Default
receipt_id	string	yes	-
tenant_id	string	no	default

Output: {content, receipt_id, tenant_id, feature_enabled, verified, signer_passport, errors: [string], http_status, report}. signer_passport may be null. With the flag off, report is omitted and errors is ["FEATURE_DISABLED"].

12.19 Agent identity

Tool	Definition	Handler	Surface	token_budget	Flag
get_agent_identity	mod.rs:1121	mod.rs:2854	[local]	-	,
resolve_principal	mod.rs:1132	resolve_principal.rs:46	[local]	-	,

get_agent_identity

No parameters. Output: {agent_name}, which is "anonymous" when no identity is authenticated (mod.rs:2855).

resolve_principal

Loopback scope sessions:read (resolve_principal.rs:25). additionalProperties: false. Proxies GET /v1/principal/resolve; tenant-scoped server-side.

Param	Type	Required	Notes
session_id	string	no	Resolve the principal bound to this hex session id
passport_id	string	no	Resolve this passport directly, for example claude-work

Resolution order: explicit session_id, then explicit passport_id, then the caller's own passport key. With none of the three available it returns INVALID_PARAMS.

Output: {content, principal: {passport_id, category, tier, tier_rank, capabilities: [string], tenant_id, agent_work_gate, resolved_via, federation_grant?}, resolved_param}. resolved_via is session, passport or identity_link:<id>.

12.20 Handoff

Tool	Definition	Handler	Surface	token_budget	Flag
create_handoff	mod.rs:1138	tools/handoff.rs:24	[local]	-	,
accept_handoff	mod.rs:1170	tools/handoff.rs:95	[local]	-	,

Observation emission from handoffs is separately gated by CORECRUXD_HANDOFF_OBSERVATIONS, default off (tools/handoff.rs:198). Restart-durable handoff signing requires CRUX_MCP_HANDOFF_SECRET; without it, signing state is in-memory only (dispatch.rs:371).

create_handoff

Param	Type	Required	Default	Constraints
session_id	string	yes	-
include_facts	boolean	no	false	Include relevant non-private facts
target_agent	string	no	-	If set, only that agent may accept
message	string	no	-
task_record	object	no	-	A structured statement of intent, so the receiver need not reconstruct the task from facts
task_record.requester	string	no	-
task_record.desired_outcome	string	no	-
task_record.sources	array<string>	no	-
task_record.acceptance_criteria	array<string>	no	-
task_record.boundaries	array<string>	no	-
task_record.blocker_rule	string	no	-

Output: {package_json, content_hash, signature, relevant_fact_count}.

accept_handoff

Param	Type	Required
package	string	yes, the JSON-encoded package returned by create_handoff

Output: {session_loaded, facts_loaded, verified, task_record?}.

12.21 Decisions

Tool	Definition	Handler	Surface	token_budget	Flag
record_decision	mod.rs:1187	decision.rs:19	[local]	-	,

Append-only, BLAKE3-hashed decision record stored as a fact. Queryable via query_facts under the entity prefix __decisions__::.

Param	Type	Required	Default
action	string	yes	-
rationale	string	yes	-
alternatives	array<string>	no	-
confidence	number	no	1.0
session_id	string	no	_default
context_refs	array<string>	no	-

Output: {decision_id, decision_hash, entity, action}.

12.22 Constraints and action enrichment

Tool	Definition	Handler	Surface	token_budget	Flag
declare_constraint	mod.rs:1215	constraint.rs:48	[local]	-	,
get_constraints	mod.rs:1247	constraint.rs:129	[local]	-	,
check_constraints	mod.rs:1274	constraint.rs:186	[local]	-	,
audit_config	mod.rs:1309	audit.rs:53	[local]	-	,
check_config_audit	mod.rs:1349	audit.rs:101	[local]	-	,
enrich_action	mod.rs:1383	action.rs:17	[local]	-	,

declare_constraint

Param	Type	Required	Default	Constraints
constraint_type	string	yes	-	One of boundary, relationship, policy, context_flag, shell_pattern. shell_pattern treats the assertion as a regex matched against tool_parameters.command for Bash and shell calls
assertion	string	yes	-	Natural-language statement
severity	string	no	medium	One of critical, high, medium, low. Critical constraints block actions

Output: {constraint_id, constraint_hash, constraint_type, assertion}.

get_constraints

Param	Type	Required	Default	Constraints
constraint_type	string	no	-	One of boundary, relationship, policy, context_flag. shell_pattern is absent from this filter enum although it is a valid write-side type; you cannot filter for shell-pattern constraints
status	string	no	active	active or suspended

Output: {constraints: [{constraint_id, constraint_type, assertion, severity, status, created_at}], count}, sorted by severity.

check_constraints

Keyword matching against constraint assertions: critical matches block, high matches warn. The schema has no required[], a bare {} is accepted.

Param	Type	Required
action_description	string	no
tool_name	string	no: when supplied, the action is deterministically enriched before matching
tool_parameters	object	no
tenant_id	string	no, included in the enrichment receipt

Output: {verdict, matched_constraints: [{constraint_id, assertion, severity, match_score}]}. verdict is pass, warn or block.

audit_config

Idempotent on sha256: re-auditing the same hash updates the path, auditor and timestamp. Records live under __ops::config-audit, keyed sha256:<hash>.

Param	Type	Required	Constraints
path	string	yes	Advisory, the hash is the canonical identity
sha256	string	yes	Lowercase 64-character hex
auditor	string	yes	Passport id, email, or free text
note	string	no	PR link, ticket, or rationale

check_config_audit

Typical caller: a SessionStart hook that has just hashed settings.json, .mcp.json and CLAUDE.md.

Param	Type	Required	Constraints
paths	array	yes	Items are {path, sha256} objects; both keys required per item

Output: {content, unaudited: [{path, sha256}], audited: [{path, sha256, audited_at, auditor, audited_path}]}.

enrich_action

The free and basic local enrichment path. Pro first-party enrichers live on the daemon HTTP route POST /v1/actions/enrich, not here.

Param	Type	Required	Default
tool_name	string	yes	-
tenant_id	string	no	-
tool_parameters	object	no	{}
action_description	string	no	-

Output: an EnrichedActionProposal of {schema, tenant_id, enrichment_mode, tool_call, narrative, affected_principals, affected_resources, state_diff, consequences, relationship_hits, consequence_metadata, enrichment_receipt}.

12.23 BYO audit trail

Tool	Definition	Handler	Surface	token_budget	Flag
audit_export_bundle	mod.rs:1420	audit_export.rs:108	[local]	required	CORECRUXD_FEATURE_AUDIT_EXPORT, default off

Builds a self-contained, signed tar.zst of every fact-event in the window plus cross-references to source receipts. It re-verifies offline via corecruxctl audit-verify, no daemon, no network.

Param	Type	Required	Default	Constraints
token_budget	integer	yes	-	Caps total tokens swept. At least 1. Omitting it fails with -32602 and the message audit_export_bundle requires token_budget (QC.2)
since_ts	string	no	-	RFC 3339, inclusive lower bound
until_ts	string	no	now	RFC 3339, exclusive upper bound
scope	object	no	-
scope.entity_prefix	string	no	-	Restrict to matching entities
scope.include_reserved	boolean	no	false	Operator-only, requires an authenticated passport plus this flag. Silently ignored for non-operator callers

Output: {content, bundle_id, bytes_path, manifest_signature_b64, fact_count, receipt_count, scope, since, until, events_jsonl_sha256, receipts_cbor_sha256}. The bundle is persisted to CORECRUXD_AUDIT_EXPORT_DIR (audit_export.rs:85).

12.24 Passport

Tool	Definition	Handler	Surface	token_budget	Flag
issue_passport	mod.rs:1455	passport.rs:236	[hosted], becoming [local] with CORECRUXD_AGENT_PASSPORTS=1	-	,
request_passport_mint	mod.rs:1476	mint_request.rs:118	[local]	-	CORECRUXD_FEATURE_PASSPORT_MINT_REQUESTS, default off, controls presence, not just the marker
get_passport	mod.rs:1502	passport.rs:369	[local]	-	,
revoke_passport	mod.rs:1515	passport.rs:479	[local]	-	CRUX_PASSPORT_REVOCATION, default off, gates access refusal, not the tool

issue_passport

Requires an authenticated agent identity. This is the only tool whose surface tier a feature flag changes (mod.rs:2446), see chapter 14.

Param	Type	Required
sponsor_id	string	no

Output: {principal_id, reputation_tier, receipt_count, sponsor_id}.

request_passport_mint

Files a self-scoped operator-approval request. It mints nothing. This is the one tool whose existence in the catalogue is flag-controlled: it is filtered out at mod.rs:2440 while the flag is off, and dispatch fails closed with -32601 (mint_request.rs:22).

Param	Type	Required	Default	Constraints
requested_category	string	no	the caller's mapped real category	One of personal, work, public
reason	string	no	-	Maximum 2048 UTF-8 bytes

Output: {request_id, requester_id, requested_category, status: 'pending'}.

get_passport

No parameters. Auto-upgrades the tier when receipt thresholds are met. Tiers: unverified, basic at 10 or more receipts, established at 100, trusted at 500, elite at 2000.

Output: {principal_id, reputation_tier, receipt_count, sponsor_id, issued_at, passport_hash}.

revoke_passport

Terminal. Supersede rather than delete.

Param	Type	Required	Default
target_passport	string	no	the caller's own passport, meaning self-revoke
reason	string	no	-

Authorised for the passport itself, the passport's sponsor, or an elite-tier operator. Writes a receipted revocation event. Output: {content, revoked target_passport, revoker_passport, reason}; isError on unauthorised calls or when there is no passport.

Revocation enforcement. When ctx.revocation_enforced is set, call_tool refuses every tool for a revoked passport except a small read-only allowlist (mod.rs:2876). It fails open: only an explicit revoked_at blocks.

12.25 Identity continuity

Tool	Definition	Handler	Surface	token_budget	Flag
passport_split	mod.rs:1544	identity.rs:195	[local]	required, minimum 1	CORECRUXD_FEATURE_IDENTITY_CONTINUITY, default off
passport_merge	mod.rs:1585	identity.rs:412	[local]	required, minimum 1	same
passport_link_device	mod.rs:1634	identity.rs:667	[local]	required, minimum 1	same

All three require the caller to hold operator tier, meaning trusted or above; cross-tenant operations are forbidden; each emits a CROWN receipt; and none is reversible at the fact level. With the flag off, all three return -32601 (identity.rs:72). Omitting token_budget returns -32602 with token_budget is required (positive integer) per QC.2 (identity.rs:90).

passport_split

Forks a passport into a new identity that inherits the source's facts via lineage read-through; future writes diverge.

Param	Type	Required	Constraints
target_passport	string	yes	Must equal the calling agent's passport
new_passport_name	string	yes	Must share the source's tenant prefix
token_budget	integer	yes	minimum: 1
reason	string	no	Recorded in the receipt body

Output: {content, new_passport_id, split_receipt_id, receipt_body_cbor_hex, receipt_body_hash_hex, tenant_id}.

passport_merge

Collapses two passports. The source is retired and its sessions become read-only references. conflict_policy is mandatory and explicit; it is never silently chosen.

Param	Type	Required	Constraints
source_passport	string	yes	Retired into the target
target_passport	string	yes	The survivor
conflict_policy	string	yes	One of prefer_source, prefer_target, error_on_conflict
token_budget	integer	yes	minimum: 1
reason	string	no

The caller must own the source or the target. Output: {content, merged_passport_id, merge_receipt_id, conflicts_resolved, conflict_policy, receipt_body_cbor_hex, receipt_body_hash_hex, tenant_id, retired_passport_id}.

passport_link_device

Param	Type	Required	Default	Constraints
device_fingerprint	string	yes	-	64-character lowercase BLAKE3 hex over the device's canonical attestation blob. Raw attestations are never stored
token_budget	integer	yes	-	minimum: 1
capabilities_subset	array<string>	no	["facts:read"]	Propagated to the linked device

Output: {content, link_receipt_id, passport_id, device_fingerprint, capabilities_subset, receipt_body_cbor_hex, receipt_body_hash_hex, tenant_id}.

12.26 Sync and update

Tool	Definition	Handler	Surface	token_budget	Flag
sync_pull	mod.rs:1673	sync.rs:88	[hosted]	-	requires CORECRUXD_SYNC_REMOTE_URL and CORECRUXD_SYNC_API_KEY
sync_push	mod.rs:1695	sync.rs:139	[hosted]	-	same
sync_status	mod.rs:1717	sync.rs:253	[local]	-	,
update_status	mod.rs:1730	update.rs:15	[local]	-	,

sync_pull and sync_push are the only two tools that are hosted-gated regardless of feature flags. See chapter 14. Unconfigured, all three sync tools return sync not configured: CORECRUXD_SYNC_REMOTE_URL is not set (sync.rs:25). sync_pull requires a basic-tier passport (sync.rs:89); sync_push requires established (sync.rs:140).

sync_pull

Pulls shared cloud tenant facts into the local mirror, resuming from the last pull cursor. Local private memory stays local.

Param	Type	Required	Notes
entity_prefix	string	no	Reserved for future use. Declared, not implemented
tenant_id	string	no	Pull the collection-aware mirror for this personal or business tenant instead of the legacy all-facts export

Output: {tenant_id?, facts_pulled, cursor, total_pull_count, collection_cursor_count}.

The handler signature is handle_sync_pull(_args, ctx) (sync.rs:88), arguments are ignored entirely, which is why entity_prefix is inert.

sync_push

Pushes only facts created locally and not previously synced. Private facts and sensitive entity prefixes are never pushed.

Param	Type	Required	Default	Notes
confirm	boolean	no	false	Without it, the call returns a preview of what would be promoted
tenant_id	string	no	-	Collection-aware tenant promotion instead of the legacy all-facts push
allowlist	array<string>	no	-	Entries such as facts, constraints, plans, collection:facts, entity:business::acme::public, or *

Output: {mode?, tenant_id?, facts_pushed?, would_promote?, preview_hash?, skipped_private?, skipped_synced?, skipped_not_allowlisted?, total_push_count?, collection_cursor_count?}. In preview, mode is tenant_promotion_preview.

sync_status

No parameters.

Output: {mode, configured, background_sync_enabled, remote_url, api_key_configured, platform_online, degraded, degraded_reason, onboarding_hint, last_pull_at, last_push_at, pull_count, push_count, collection_pull_cursor_count, collection_push_cursor_count, tenant_manifest_supported, local_fact_count}. Modes: local-only, cloud-mirror configured, full background sync, degraded.

update_status

No parameters.

Output: {enabled, state, basis, tracking_ref, current_commit, binary_commit, latest_commit, ahead_by, behind_by, checkout_commit, checkout_ahead_by, checkout_behind_by, checked_at, error, comparison_stale, upgrade_hint, upgrade_playbook_query, backup_playbook_query}.

basis distinguishes "binary", the running binary's embedded commit, which is the deploy-gating number, from "checkout", the source-tree HEAD, which is the fallback. The checkout_* fields expose a stale source clone.

12.27 Context-custody audit

Tool	Definition	Handler	Surface	token_budget	Flag
context_custody_audit	mod.rs:1747	context_custody_audit.rs:299	[local]	advisory only	CRUX_CONTEXT_CUSTODY_AUDIT, default off

Scores this Crux instance against the context-custody exit test: four questions (SEE, DO, REMEMBER, CHECK) and the exit test (EXPORT, INSPECT, REVOKE, ROUTE, KEEP-LOCAL, PROVE). A pure read.

Param	Type	Required	Notes
token_budget	integer	no	Advisory only. Never read by the handler; the scorecard is fixed-size (context_custody_audit.rs:56)

Output: {daemon_version, four_questions: [{axis, question, verdict, evidence}], exit_test: [...], lock_in_risk, lock_in_label, trust_posture: {recommendations: [string], standing_gap}, thesis, note}. lock_in_risk is 1 to 5. With the flag off: {enabled: false, note}.

One honesty property worth knowing: each verdict reports the runtime state, so a capability that is gated off scores partial rather than strong, and each verdict cites the backing capability. The scorecard cannot overclaim. Its inputs read CRUX_PASSPORT_REVOCATION, CRUX_AGENT_CARD, CORECRUXD_FEATURE_RECEIPT_VERIFY, CORECRUXD_FEATURE_AUDIT_EXPORT, router presence, sync-remote configuration and the local fact count.

This flag uses parsing dialect 3, where yes counts as ON, unlike most of the flags in this chapter. See 15.1.

---

Continue to chapter 13 for the remaining 49 tools.

Sources

• crates/crux-mcp/src/tools/mod.rs:163, the ToolDefinition literals, in catalogue order
• crates/crux-mcp/src/tools/mod.rs:2728, tool_output_docs, the output contract
• crates/crux-mcp/src/tools/mod.rs:2881, call_tool dispatch arms
• crates/vaultcrux-local/src/tool_surface.rs:215, marker_for_tool

All line references were verified at commit 93b41a7.