MCP tools

Carabase ships a Model Context Protocol server that exposes the host’s retrieval layer as callable tools. Any MCP client can consume it — the OpenClaw gateway, Claude Desktop, Cursor, Codex, the MCP Inspector — over Streamable HTTP at /mcp (and the legacy SSE surface at /mcp/sse). The in-process agent runtimes and chat engines call the same tools directly.

The canonical tool surface is a single, DB-agnostic source of truth that any consumer can import. Its complete list, with each tool’s description and input schema, is exported as packages/mcp-server/generated/tool-contracts.json (regenerated by pnpm gen:mcp-tool-contracts); that file, not this page, is the authority on which tools exist. The host mounts that surface, adds tools of its own beside it, and registers two legacy aliases (search_semantic → carabase_search_semantic, query_graph → carabase_search_graph).

The canonical tools

Every canonical tool is read-only. Together they are the only retrieval surface an external MCP client or an in-process ReAct loop can reach.

carabase_search_semantic(query, limit?)

Semantic vector search across artifacts (documents, notes, memories, knowledge). Returns the top limit (default 5) chunks ranked by similarity, each with a carabase://artifact/<id> resource URI for the full body. When the workspace has unified embeddings enabled, this runs as a dual-leg (legacy-1536 + unified-1024) search fused with reciprocal rank fusion — fused hits carry an rrf_score, single-leg hits carry a cosine score.

{ "query": "what did Alice say about pricing?", "limit": 5 }

carabase_search_graph(entity, depth?, min_confidence?, source_kinds?, as_of?, include_invalid?)

Knowledge-graph traversal from a named entity. Walks edges up to depth hops (clamped to 1–3, default 1), optionally filtering by edge confidence and provenance. Honest confidence scores — there is no default min_confidence; you opt in.

{ "entity": "Alice Chen", "depth": 2, "min_confidence": 0.6, "source_kinds": ["extracted"] }

source_kinds accepts "extracted" (directly observed), "inferred" (LLM/curator-derived), and/or "ambiguous" (awaiting human review). as_of (ISO-8601) time-travels the graph to facts that were valid at that instant; include_invalid returns both currently-valid and superseded edges, each rendered with its [valid_at – invalid_at] interval. By default only currently-valid facts are returned.

carabase_query_metadata(tags?, date_after?, date_before?, source?, entity_name?, limit?)

Structured filter over artifact columns — the only leg that accepts a temporal range. Combine tags (AND semantics), a created_at date window, a source substring, and a linked entity_name. Use this for “what did I write last Tuesday?” type questions.

{ "entity_name": "Acme Corp", "date_after": "2026-01-01", "tags": ["contract"], "limit": 10 }

carabase_find_entity_candidates(name, limit?)

Disambiguation lookup — given a name fragment (“Alice”), returns candidate canonical entities plus their context, so the agent can resolve the right one before traversing the graph.

carabase_route_and_execute(query, concept_root_ids?, cursor?)

Cross-strategy router. Classifies the query, resolves primary entities, runs the appropriate strategies, and returns the fused result set ranked by relevance. The top hits (up to 10) are hydrated with a query-anchored snippet; any remainder is reported as a count plus a cursor you pass back to page the next batch. The default entry point when the agent doesn’t want to compose tools itself.

{ "query": "everything about the Q3 roadmap" }

carabase_query_timeseries(source, metric, range, aggregation?, group_by?)

Substrate-table time-series queries. Reads pre-aggregated rows from connector substrate tables (Strava, Spotify, Last.fm, Whoop, and others declared via a manifest’s substrateTable block) so the agent doesn’t re-aggregate downstream. range (with both from and to) is required — there is no default window.

{ "source": "strava", "metric": "distance_meters", "aggregation": "sum", "group_by": "week", "range": { "from": "2026-01-01", "to": "2026-05-01" } }

group_by accepts "day" | "week" | "month" for time bucketing, or the metric’s categorical column (e.g. "activity_type" for Strava). When the underlying substrate has been purged out from under the aggregate, the result carries metadata.aggregate_status: "aggregate_only" so the agent can present a freshness caveat.

carabase_resolve_mesh_uri(uri)

Just-in-time mesh resolver for hollow / metadata-only artifacts. Hydrates the body from the source connector at query time, compacted to a token budget, and returns provenance (connector, uri, fetched_at). The host-side resolver enforces a capability and budget ladder (connector capability → per-account flag → token caps → daily budget → per-workspace concurrency). REST companion: POST /api/v1/mesh/resolve.

carabase_verify_hypothesis(claim, limit?)

Corroborate vs. contradict a natural-language claim against retrieved evidence.

{
  "verdict": "corroborated" | "contradicted" | "mixed" | "inconclusive",
  "corroborated_by": [...],
  "contradicted_by": [...]
}

It uses an LLM entailment judge (per-snippet supports/refutes/neutral), degrading to a lexical overlap/negation heuristic when no judge is wired.

carabase_traverse_memory_network(anchor[], mode?, depth?, link_types?, min_confidence?, limit?)

Personalized PageRank over the memory-network typed graph. Seeds at anchor[] (memory UUIDs — keyword anchoring requires a prior carabase_search_semantic call to resolve IDs first), walks typed edges filtered by link_types and min_confidence, and returns the top memories ranked by stationary distribution. Modes: "pagerank" (default), "shortest_path", "neighbours"; depth 1–3 (default 2).

carabase_search_visual(query, limit?, source_kinds?)

Text→image nearest-neighbour search over the 1024-dim image_embeddings space (the same basis photo bytes are embedded into). Finds photos by description.

carabase_search_multimodal(query, limit?, text_weight?, visual_weight?)

Fuses the text and image legs into one ranked set (reciprocal rank fusion with per-leg dedup and a matched_via accumulator), for queries that span documents and photos. Optional text_weight / visual_weight bias the fusion.

carabase_scan_mesh(...)

Read-only self-survey of the workspace mesh, used by the nightly mesh-scan cron and the proposal skills (gated per skill by an opt-in flag). Filters by date range, tags, metadata key/value, and source.

carabase_read_folio(slug?, id?, kind?, status?, limit?)

Read a synthesized folio’s narrative and its citations, so taste / domain / project questions are answered from the cited narrative instead of re-derived from raw hits. Pass slug or id to fetch one folio (slug wins if both); omit them to list folios filtered by kind (taste / domain / project) and status.

carabase_search_lexical(query, kinds?, limit?)

pg_trgm fuzzy/substring grep for rare proper nouns and “grep my notes for X” queries that cosine semantic search structurally abstains on. The agent leg runs at a raised trigram threshold (0.5) to cap the multi-word fan-out; the desktop Summon Bar keeps the Postgres default (0.3).

carabase_term_timeline(query? | entity? | source?, kinds?, date_after?, date_before?, bucket?, limit_scan?)

When something starts or stops appearing (era edges), and how often it appears over time. Deterministic (no LLM): for exactly one of a literal query term, an entity (an id or exact name; aliases merged into it count too) or a source, it counts matching items per month or year on the effective content date (when the thing happened, never when it was ingested) and returns the first and last matching artifacts with their carabase://artifact/<id> URIs. An item with no content date is counted as undated, never bucketed, and an email or file split into chunks counts once. The scan is capped by limit_scan (default 5,000, max 20,000), and the result says when it was truncated.

{ "query": "Acme Corp", "bucket": "year", "date_after": "2020" }

carabase_resolve_person(identifier? | name?, kind?, issuer_scope?)

Deterministic person lookup in the workspace’s confirmed identity index (no LLM), in either direction. Pass exactly one of identifier (who is this phone number, handle or email address?) or name (what are this person’s confirmed identifiers?). The outcome is resolved, observed_unconfirmed (identifier lookups only), ambiguous (it never guesses a winner) or not_found.

carabase_read_artifact(id | uri, offset?, max_chars?)

The tool form of resources/read on carabase://artifact/{id}, for MCP clients that can call tools but cannot read resources. It returns the same text, under the same access, purge and metadata-only handling, because both use one reader. id takes a bare artifact id or the whole URI. Long bodies are paged (default 20,000 characters, max 60,000): the provenance block repeats on every page, and a [page: …] trailer gives the next offset. The in-process runtimes register a different tool under this name; see below.

carabase_project_context(folio, task, target_paths?, head_sha?, max_chars?)

Compiles the project context pack for one code-project folio before an agent changes code: governing decisions, live initiatives, recent implementation sessions, open gaps and mechanical contradictions, each traced to a stored citation. It is deterministic (no LLM, no writes) and needs an explicit folio; it never searches for a project. target_paths ranks decisions and prior sessions by the files they govern.

Host tools on /mcp

The host registers more tools of its own on /mcp, over substrate the retrieval package cannot see. They are not part of the canonical surface or of tool-contracts.json. A tool that changes the workspace is registered only for a read-write session, so a read-only token never sees it in tools/list.

commit_to_folio(folio_id | folio_name, content)

A write tool. Adds a commit to an existing folio, named by exactly one of folio_id (exact) or folio_name (matched case-insensitively, then by substring). It never creates a folio: a target that matches nothing writes nothing, and the error lists the folios that do exist. The commit is pinned, so the folio never evicts it automatically.

The other host tools

The rest cover project memory (project records, Context Commit proposals, Catch up), Life eras, Carabase Tables and Documents, shared backfills, folio charter and About edits, daily-note tasks, curation review, agent-assisted integration setup, skill-backed tools such as carabase_recall_memory and carabase_personal_context, and the tools that connector plugins contribute. A client’s tools/list shows the ones its token can reach.

In-process-only tools

These run only in the in-process agent runtime and chat path. They are not served over /mcp.

carabase_read_artifact (in-process)

The canonical carabase_read_artifact is what /mcp serves. The in-process agent runtime and chat engines register their own tool of the same name instead: the snippet→full-body hydration tool, which fetches a complete artifact body (and an email’s attachments). It exists because the AI-SDK ReAct loop cannot call the MCP resources/read verb that the carabase://artifact/{id} resource serves. It retries once then emits a typed [hydration_failed] signal rather than a bare “not found”, resolves a backing artifact for a graph entity that has no directly-readable body, and memoizes by id through a per-run cache so a chunked document hydrates once.

carabase_attach_file / carabase_commit_session

Available only in the in-process agent-runtime path. carabase_attach_file attaches a file artifact to the originating logCard of an agentic-flow run; carabase_commit_session commits a captured AI coding session into its bound project folio(s). Write tools are denied when a run holds a read-only MCP token.

External MCP servers

The agent runtime can additionally pull tools from per-workspace external MCP servers registered for the workspace. At session start the runtime queries each enabled server, namespaces its tool list, and lays the discovered tools alongside the canonical Carabase surface. Failures are isolated per server, so a down external endpoint never breaks the canonical tools. This is how, for example, a local Beeper Desktop MCP endpoint can be exposed to the agent.

Resources

The MCP server also exposes resources (URIs the client can call resources/read on):

URI pattern	What it returns
carabase://artifact/{id}	Lazy artifact body fetch. Tool results return URIs of this form so the client only fetches the bodies it actually needs.
folio://{id}/readme	Folio name + README summary.

When folio proactive priming or the mesh surface map are enabled, additional gated resources register: carabase://surfaces (a read-only link index of connected accounts, folios, skills, and external MCP servers) and an owner-context surface under carabase://folios/leads. When disabled, these are unregistered entirely — they do not appear in resources/list.

Hint repair

When a Carabase tool returns 0 results or an error, Carabase appends a structured [hint: ...] and [trace: ...] trailer to the response so the agent can course-correct without resetting its chain of thought (for example, suggesting the metrics or aggregations a substrate actually supports). Hints are deterministic — no extra LLM call.

Format-aware compaction

Artifact bodies fetched through carabase://artifact/{id} can be auto-compacted to fit a token budget: CSVs preserve the header plus matching rows, markdown keeps headings plus relevant paragraphs, and PDFs split by page and rank pages by query-token frequency. This is opt-in via the tool context and off by default in the host shim.