# GhostCrab MCP Tools Reference

> Generated by `node scripts/export-operator-catalog.mjs` from the compiled MCP registry. Do not hand-edit tool entries.

GhostCrab exposes 64 registered MCP tools, all returned by MCP `tools/list` and directly callable by name. A curated subset of 13 is flagged as recommended defaults (`title: GhostCrab recommended default`); the other 51 are extended tools. Use `gcp tools list`, `gcp tools verify`, and `ghostcrab_tool_search` for discovery metadata and domain filtering.

All successful tool calls use the additive envelope:

```json
{
  "ok": true,
  "tool": "ghostcrab_status",
  "surface_version": "2026-06-10",
  "generated_at": "2026-06-11T09:45:58.927Z"
}
```

Tool-specific fields are added next to that envelope. Structured failures use the same envelope with `ok: false` and `error.code`.

## Tools

### `ghostcrab_artifact_get`

Read. Fetch one answer artifact from the registry by artifact_id (analysis plan, live answer, snapshot, or evidence pack). Returns public_label for user-facing text. Use ghostcrab_tool_search to discover this extended tool.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | pragma |
| Access | read |
| Required arguments | `artifact_id` |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `artifact_id` | yes | `string` | Registry id, e.g. live_answer_view__pilotage_hebdomadaire or analysis_plan__scope_slug. |
| `workspace_id` | no | `string` | Optional workspace context for the call (does not filter the registry row). |

### `ghostcrab_collection_facet_search`

Read. Search collection facets for a workspace/collection. After reindex, reads Roaring bitmaps from facet_postings (namespace+dimension required). Falls back to facet_assignments_raw when postings are absent or namespace/dimension are omitted. Extended tool for collection-imported taxonomy facets (distinct from agent facets table).

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | graph |
| Access | read |
| Required arguments | `collection_id` |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `workspace_id` | no | `string` | Target workspace id. Defaults to session workspace. |
| `collection_id` | yes | `string` | Collection id within the workspace. |
| `table_id` | no | `integer` | Optional facet table id (facet_tables.table_id). When set, enables facet_postings Roaring search after reindex. |
| `namespace` | no | `string` | Optional ontology namespace filter. |
| `dimension` | no | `string` | Optional facet dimension filter. |
| `value` | no | `string` | Optional substring match on facet value. |
| `limit` | no | `integer` | - |

### `ghostcrab_collection_reindex`

Write. Rebuild BM25, collection facet postings, and graph derived indexes for a workspace collection via native MindBrain reindexAll.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | graph |
| Access | write |
| Required arguments | `collection_id`, `table_id` |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `workspace_id` | no | `string` | Target workspace id. Overrides session context for this call only. |
| `collection_id` | yes | `string` | Collection id whose raw documents and facets are reindexed. |
| `table_id` | yes | `integer` | Facet/search table id used for BM25, facet_postings, and graph projection. |

### `ghostcrab_combined_search`

Read. Graph-first combined search across graph entities/relations and linked facet facts. Use when the caller does not know whether data lives in graph or facets.

| Field | Value |
|-------|-------|
| Visibility | basic |
| Subsystem | facets |
| Access | read |
| Required arguments | none |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `query` | no | `string` | Text query used first against graph entities, then against facets as fallback. |
| `workspace_id` | no | `string` | Target workspace id. Overrides session context for this call only. |
| `collection_id` | no | `string\|null` | Optional graph collection scope. Omit or pass null to search all collections in the workspace. |
| `limit` | no | `integer` | Maximum number of combined ranked results to return. |
| `graph_limit` | no | `integer` | Maximum graph entities to inspect before linked facet lookup. Defaults to max(20, limit * 2). |
| `facet_limit` | no | `integer` | Maximum linked or fallback facet facts to retrieve. Defaults to max(20, limit * 2). |
| `entity_types` | no | `array` | Optional graph_entity.entity_type filters. Empty array searches all graph entity types. |
| `metadata_filters` | no | `object` | Exact graph metadata filters. |
| `facet_schema_id` | no | `string` | Optional schema_id filter applied to linked and fallback facets. |
| `facet_filters` | no | `object` | Exact facet filters applied to linked and fallback facet facts. Arrays are treated as OR. |
| `facet_mode` | no | `string` | Ranking mode used by the facet fallback search. |
| `collection_facet_table_id` | no | `integer` | Optional facet_tables.table_id for the collection-facet fallback. Provide with collection_facet_namespace + collection_facet_dimension to force the facet_postings (Roaring) path. When omitted, the fallback tries to auto-resolve a single posting-backed dimension for the collection, else scans facet_assignments_raw. |
| `collection_facet_namespace` | no | `string` | Optional ontology namespace for the collection-facet fallback. Required (with collection_facet_dimension) to hit facet_postings explicitly. |
| `collection_facet_dimension` | no | `string` | Optional facet dimension for the collection-facet fallback. Required (with collection_facet_namespace) to hit facet_postings explicitly. |
| `include_relations` | no | `boolean` | Include graph_relation rows touching returned graph entities. Off by default to keep payloads bounded; set true when relation topology is needed. |
| `include_chunks` | no | `boolean` | Include graph_entity_chunk evidence for returned graph entities when available. |
| `chunk_limit` | no | `integer` | Maximum chunk evidence rows to return when include_chunks is true. Defaults to min(50, limit * 5). |

### `ghostcrab_count`

Count items grouped by facet dimensions without loading the full content.

| Field | Value |
|-------|-------|
| Visibility | basic |
| Subsystem | facets |
| Access | read |
| Required arguments | `group_by` |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `schema_id` | no | `string` | - |
| `group_by` | yes | `array` | - |
| `filters` | no | `object` | Optional facet filters applied before counting. |
| `workspace_id` | no | `string` | Target workspace id. Overrides session context for this call only. |

### `ghostcrab_coverage`

Read. Ontology/taxonomy instantiation coverage: which schema nodes are not yet reflected as graph instances. Complements ghostcrab_graph_diagnostics (instance invariants + native checks) and ghostcrab_graph_gap_rules (closed-world contract). Requires domain (workspace id or domain name). Example: { "domain": "immeuble-demo" }. Returns coverage_score, gap_nodes, can_proceed_autonomously, recommended_action.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | graph |
| Access | read |
| Required arguments | `domain` |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `domain` | yes | `string` | Domain or workspace id to check. Required. Example: immeuble-demo or ghostcrab-product. |
| `agent_id` | no | `string` | - |
| `workspace_id` | no | `string` | Optional session override. domain is still required; this only adjusts response context. |
| `entity_type` | no | `array` | Restrict coverage check to these entity types only (e.g. ["concept", "skill"]). |

### `ghostcrab_csearch`

Read. Alias for ghostcrab_combined_search. Graph-first combined search across graph entities/relations and linked facet facts.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | facets |
| Access | read |
| Required arguments | none |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `query` | no | `string` | Text query used first against graph entities, then against facets as fallback. |
| `workspace_id` | no | `string` | Target workspace id. Overrides session context for this call only. |
| `collection_id` | no | `string\|null` | Optional graph collection scope. Omit or pass null to search all collections in the workspace. |
| `limit` | no | `integer` | Maximum number of combined ranked results to return. |
| `graph_limit` | no | `integer` | Maximum graph entities to inspect before linked facet lookup. Defaults to max(20, limit * 2). |
| `facet_limit` | no | `integer` | Maximum linked or fallback facet facts to retrieve. Defaults to max(20, limit * 2). |
| `entity_types` | no | `array` | Optional graph_entity.entity_type filters. Empty array searches all graph entity types. |
| `metadata_filters` | no | `object` | Exact graph metadata filters. |
| `facet_schema_id` | no | `string` | Optional schema_id filter applied to linked and fallback facets. |
| `facet_filters` | no | `object` | Exact facet filters applied to linked and fallback facet facts. Arrays are treated as OR. |
| `facet_mode` | no | `string` | Ranking mode used by the facet fallback search. |
| `collection_facet_table_id` | no | `integer` | Optional facet_tables.table_id for the collection-facet fallback. Provide with collection_facet_namespace + collection_facet_dimension to force the facet_postings (Roaring) path. When omitted, the fallback tries to auto-resolve a single posting-backed dimension for the collection, else scans facet_assignments_raw. |
| `collection_facet_namespace` | no | `string` | Optional ontology namespace for the collection-facet fallback. Required (with collection_facet_dimension) to hit facet_postings explicitly. |
| `collection_facet_dimension` | no | `string` | Optional facet dimension for the collection-facet fallback. Required (with collection_facet_namespace) to hit facet_postings explicitly. |
| `include_relations` | no | `boolean` | Include graph_relation rows touching returned graph entities. Off by default to keep payloads bounded; set true when relation topology is needed. |
| `include_chunks` | no | `boolean` | Include graph_entity_chunk evidence for returned graph entities when available. |
| `chunk_limit` | no | `integer` | Maximum chunk evidence rows to return when include_chunks is true. Defaults to min(50, limit * 5). |

### `ghostcrab_ddl_execute`

Execute an approved DDL migration. The migration must have status='approved' (set via CLI ddl-approve).

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | workspace |
| Access | model |
| Required arguments | `migration_id` |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `migration_id` | yes | `string` | UUID of the migration to execute (must be 'approved'). |

### `ghostcrab_ddl_list_pending`

List DDL migrations from the pending queue. Filter by workspace or status.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | workspace |
| Access | model |
| Required arguments | none |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `workspace_id` | no | `string` | Filter by workspace. Omit for all workspaces. |
| `status` | no | `string` | Filter by migration status. Omit for all. |

### `ghostcrab_ddl_propose`

Propose a DDL migration for human review. The SQL is stored in pending_migrations with status='pending'. DROP and TRUNCATE statements are rejected.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | workspace |
| Access | model |
| Required arguments | `workspace_id`, `sql` |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `workspace_id` | yes | `string` | Target workspace id. |
| `sql` | yes | `string` | DDL SQL to propose (CREATE TABLE, ALTER TABLE, CREATE INDEX…). DROP and TRUNCATE are blocked. |
| `rationale` | no | `string` | Why this migration is needed. |
| `proposed_by` | no | `string` | Agent or user identity submitting this proposal. |
| `sync_spec` | no | `object` | Unsupported in SQLite-only GhostCrab. Kept in the schema only to return a clear compatibility error for old callers. |
| `table_semantics` | no | `array` | Optional semantic annotations per table. If omitted (and column/relation blocks omitted), basic semantics are inferred from sql + sync_spec. |
| `column_semantics` | no | `array` | Optional per-column roles. Used together with or without table_semantics. |
| `relation_semantics` | no | `array` | Optional declared relations between tables. |

### `ghostcrab_entity_chunks`

Read. Return graph_entity_chunk links, optionally joined to raw chunk/document content, for an entity or workspace collection scope.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | graph |
| Access | read |
| Required arguments | none |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `workspace_id` | no | `string` | Target workspace id. Overrides session context for this call only. |
| `entity_id` | no | `integer` | Exact graph_entity.entity_id. |
| `entity_name` | no | `string` | Optional graph_entity.name filter. Use with entity_type when names may collide. |
| `entity_type` | no | `string` | Optional graph_entity.entity_type filter. |
| `collection_id` | no | `string` | Optional collection scope. |
| `doc_id` | no | `integer` | Optional raw document id filter. |
| `chunk_index` | no | `integer` | Optional raw chunk index filter. |
| `include_content` | no | `boolean` | Include chunks_raw.content and document metadata when available. |
| `limit` | no | `integer` | - |

### `ghostcrab_facet_catalog`

Read. List the declared GhostCrab facet vocabulary and its native registration state.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | facets |
| Access | read |
| Required arguments | none |

_No input arguments._

### `ghostcrab_facet_inspect`

Read. Inspect a single facet definition and its persisted/runtime state.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | facets |
| Access | read |
| Required arguments | `facet_name` |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `workspace_id` | no | `string` | Target workspace id. Overrides session context for this call only. |
| `facet_name` | yes | `string` | - |

### `ghostcrab_facet_register`

Write. Register or update a facet definition in the durable facet-definition store.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | facets |
| Access | write |
| Required arguments | `definition` |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `workspace_id` | no | `string` | Target workspace id. Overrides session context for this call only. |
| `definition` | yes | `object` | - |

### `ghostcrab_facet_validate`

Read. Validate facet keys against the declared vocabulary before writing or importing records.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | facets |
| Access | read |
| Required arguments | none |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `strict` | no | `boolean` | - |
| `record` | no | `object` | - |
| `records` | no | `array` | - |

### `ghostcrab_graph_diagnostics`

Read. Unified graph gap report after closed-world rules are loaded. Evaluates imported gap rules (missing_required_relation, too_many_relations) plus native checks: isolated_entity, small_component, relation_type_mismatch, entity_without_evidence, relation_without_evidence, ontology_coverage_gap. Not a substitute for ghostcrab_coverage (schema instantiation) or ghostcrab_graph_gap_rules (rule audit). Workflow: import rules → list rules → run diagnostics. Example: { "workspace_id": "immeuble-demo" }.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | graph |
| Access | read |
| Required arguments | none |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `workspace_id` | no | `string` | Target workspace id. Defaults to the current MCP session workspace. Example: immeuble-demo. |
| `ontology_id` | no | `string` | Optional ontology id. When omitted, MindBrain uses the workspace default ontology (e.g. immeuble-demo::core). |
| `limit` | no | `integer` | Maximum issue rows to return. |
| `component_small_max` | no | `integer` | Weak connected components with this many nodes or fewer are reported as small components. |

### `ghostcrab_graph_gap_rules`

Read. List active closed-world gap rules (rule_id, entity/relation types, direction, min/max counts, severity, enabled, metadata). Use before and after ghostcrab_graph_gap_rules_import to audit the contract. Returns global rules (workspace_id null) plus workspace-scoped rules. Example: { "workspace_id": "immeuble-demo" }. Pair with ghostcrab_graph_diagnostics to see violations.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | graph |
| Access | read |
| Required arguments | none |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `workspace_id` | no | `string` | Workspace id used to resolve the default ontology and include workspace-scoped rules. Example: immeuble-demo. |
| `ontology_id` | no | `string` | Ontology id to inspect directly. When omitted, uses the workspace default ontology. |

### `ghostcrab_graph_gap_rules_delete`

Write. Delete one or more closed-world gap rules by rule_id. Prefer enabled:false on ghostcrab_graph_gap_rules_import to disable without deleting. For bulk replacement of a rule pack, use replace:true on import instead. Optional ontology_id and workspace_id scope the delete for safety.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | graph |
| Access | write |
| Required arguments | `rule_ids` |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `rule_ids` | yes | `array` | Rule ids to delete, e.g. ["leased-unit-has-lease"]. |
| `ontology_id` | no | `string` | Optional ontology scope. When set, only rules for this ontology are deleted. |
| `workspace_id` | no | `string` | Optional workspace scope. When set with ontology_id, restricts deletion to that workspace. |

### `ghostcrab_graph_gap_rules_import`

Write. Import closed-world gap rules: unary cardinality checks per entity_type and relation_type (e.g. each unit must have exactly one assigned_cellar). Upserts by rule_id; set replace:true to delete all rules in the ontology+workspace scope before import (use when switching rule packs L0→L2). Disable a rule with enabled:false instead of deleting. Then list via ghostcrab_graph_gap_rules and validate via ghostcrab_graph_diagnostics. Accepts the full gap-rules JSON envelope (ontology_id, workspace_id, replace, rules).

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | graph |
| Access | write |
| Required arguments | `ontology_id`, `rules` |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `ontology_id` | yes | `string` | Ontology id the rules belong to. Example: immeuble-demo::core. |
| `workspace_id` | no | `string` | Optional workspace scope for workspace-specific rules. Example: immeuble-demo. Defaults to MCP session workspace. |
| `replace` | no | `boolean` | When true, delete all existing rules for this ontology_id and workspace_id scope before importing. When false (default), upsert each rule_id without removing omitted rules. |
| `rules` | yes | `array` | Closed-world rules. Each rule checks relation counts for entities of entity_type. |

### `ghostcrab_graph_path`

Read. Find the shortest path between two graph entities by node ID (source → target). Returns a human-readable path summary or an empty result when no path exists within max_depth hops.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | graph |
| Access | read |
| Required arguments | `source`, `target` |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `workspace_id` | no | `string` | Target workspace id. Overrides session context for this call only. |
| `source` | yes | `string` | Source node ID (graph_entity.node_id or entity_id). |
| `target` | yes | `string` | Target node ID (graph_entity.node_id or entity_id). |
| `max_depth` | no | `integer` | Maximum number of hops to search. |
| `edge_labels` | no | `array` | Optional edge label filters. Empty array searches all edge types. |

### `ghostcrab_graph_reindex`

Write. Rebuild derived graph_entity, graph_relation, graph_entity_document, and graph_entity_chunk rows from MindBrain raw collection graph tables for a workspace. Prefers native MindBrain reindex (includes adjacency rebuild) with SQL fallback.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | graph |
| Access | write |
| Required arguments | none |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `workspace_id` | no | `string` | Target workspace id. Overrides session context for this call only. |
| `document_table_id` | no | `integer` | Optional facet table_id used when projecting entity_documents_raw into graph_entity_document. |
| `include_document_links` | no | `boolean` | When true and document_table_id is provided, rebuild graph_entity_document links for the workspace. |
| `include_chunk_links` | no | `boolean` | When true, rebuild graph_entity_chunk links for the workspace. |

### `ghostcrab_graph_search`

Read. Search graph_entity runtime data by text, entity type, collection_id, and metadata filters. Use this for imported graph entities such as ProjectionResult, SEOIssue, or PageAuditSnapshot.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | graph |
| Access | read |
| Required arguments | none |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `workspace_id` | no | `string` | Target workspace id. Overrides session context for this call only. |
| `collection_id` | no | `string\|null` | Optional collection scope. Omit or pass null to search all collections in the workspace. |
| `query` | no | `string` | Text query matched against entity name, entity type, and metadata_json. Empty string means filter-only search. |
| `entity_types` | no | `array` | Optional graph_entity.entity_type filters. Empty array searches all entity types. |
| `metadata_filters` | no | `object` | Exact metadata_json filters. Example: {"projection_id":"proj_keyword_opportunities"}. |
| `include_relations` | no | `boolean` | Include graph_relation rows touching returned entities. |
| `limit` | no | `integer` | - |

### `ghostcrab_graph_subgraph`

Read. Expand a subgraph around one or more seed entity IDs within a given number of hops. Returns the stream of graph events (nodes and edges) reachable from the seeds.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | graph |
| Access | read |
| Required arguments | `seed_ids` |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `workspace_id` | no | `string` | Target workspace id. Overrides session context for this call only. |
| `seed_ids` | yes | `array` | Entity IDs to use as seeds for subgraph expansion. |
| `hops` | no | `integer` | Number of hops to expand from each seed. |
| `edge_types` | no | `array` | Optional edge type filters. Empty array traverses all edge types. |

### `ghostcrab_learn`

Write. Upsert knowledge graph nodes and directed edges for durable structural relations (blockers, dependencies, conceptual links). Do not create graph structure before the user intent is clarified on the first fuzzy onboarding turn.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | graph |
| Access | write |
| Required arguments | none |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `node` | no | `object` | - |
| `edge` | no | `object` | - |
| `workspace_id` | no | `string` | Target workspace id. Overrides session context for this call only. |

### `ghostcrab_live_refresh`

Write. Explicitly refresh one live answer view (Données en direct) from current graph/facts. Requires one exact artifact_id such as live_answer_view__pilotage_hebdomadaire; wildcards/globs are not supported. Bumps current_version and records an answer_update_event. Only valid for live_answer_view artifacts. Use ghostcrab_tool_search to discover this extended tool.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | pragma |
| Access | write |
| Required arguments | `artifact_id` |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `artifact_id` | yes | `string` | Exact live answer artifact id (live_answer_view__…). Wildcards/globs such as live_answer_view__foo_* are not supported. |
| `workspace_id` | no | `string` | Optional workspace context for the call. |
| `include_latest_event` | no | `boolean` | When true, attach the latest answer_update_event row after refresh. |

### `ghostcrab_loadout_apply`

Write. Bind a predefined ontology loadout to a workspace by updating domain_profile.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | loadout |
| Access | write |
| Required arguments | `workspace_id`, `loadout_id` |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `workspace_id` | yes | `string` | Target workspace id. |
| `loadout_id` | yes | `string` | - |
| `overwrite` | no | `boolean` | Allow replacing an already selected different loadout. |

### `ghostcrab_loadout_inspect`

Read. Inspect a predefined ontology loadout, including questions the LLM should ask next.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | loadout |
| Access | read |
| Required arguments | `loadout_id` |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `loadout_id` | yes | `string` | - |

### `ghostcrab_loadout_list`

Read. List predefined ontology loadouts and the recommended default starter.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | loadout |
| Access | read |
| Required arguments | none |

_No input arguments._

### `ghostcrab_loadout_seed`

Write. Seed the graph and semantic placeholders for a predefined ontology loadout into a workspace.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | loadout |
| Access | write |
| Required arguments | `workspace_id`, `loadout_id` |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `workspace_id` | yes | `string` | - |
| `loadout_id` | yes | `string` | - |
| `persist_semantics` | no | `boolean` | Also persist placeholder semantic table/column/relation definitions. |

### `ghostcrab_loadout_suggest`

Read. Suggest the best ontology loadouts for a workspace goal or ontology description.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | loadout |
| Access | read |
| Required arguments | `goal` |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `goal` | yes | `string` | Free-text description of the workspace, ontology, or domain. |
| `limit` | no | `integer` | Maximum number of suggestions to return. |

### `ghostcrab_modeling_guidance`

Bootstrap. Describe your domain goal in natural language and get matched activity families, clarifying questions, and a step-by-step modeling plan. Call this when you want to build a new domain model (CRM, kanban, knowledge base, etc.).

| Field | Value |
|-------|-------|
| Visibility | basic |
| Subsystem | pragma |
| Access | guide |
| Required arguments | `goal` |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `goal` | yes | `string` | Natural-language description of what you want to model or build. Examples: 'I want to create a CRM tool to manage my prospecting campaigns', 'un outil kanban pour suivre mes tâches'. |
| `workspace_id` | no | `string` | Optional. Existing workspace to scope this guidance to. If omitted, the response will suggest creating a new workspace. |

### `ghostcrab_onboarding_schemas`

Bootstrap. Return the curated schema ids most useful during domain modeling onboarding.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | facets |
| Access | read |
| Required arguments | none |

_No input arguments._

### `ghostcrab_ontology_import`

Write. Import a real ontology into MindBrain native ontology tables from LinkML YAML or OWL/RDF N-Triples. This is the MCP counterpart to gcp brain ontology compile/import; do not use remember, learn, schema_register, or graph_gap_rules_import for ontology source files. Defaults to LinkML because that is the Personal ontology authoring path.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | ontology |
| Access | write |
| Required arguments | `ontology_id`, `input_path` |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `workspace_id` | no | `string` | Target workspace id. Defaults to the current MCP session workspace. |
| `ontology_id` | yes | `string` | Stable ontology id to write, for example serenity-production::core. |
| `input_path` | yes | `string` | Local path readable by the MCP server. For source_format=linkml, pass ontology/core.yaml. For ntriples, pass an .nt file. |
| `source_format` | no | `string` | Input format. linkml compiles YAML directly into native ontology tables; ntriples imports OWL/RDF N-Triples. |
| `output_path` | no | `string` | Optional LinkML compile bundle output path. Applies only to source_format=linkml. |
| `ntriples_path` | no | `string` | Optional generated N-Triples output path. Applies only to source_format=linkml. |
| `profile` | no | `string` | Optional LinkML compile profile, for example syndic. Applies only to source_format=linkml. |
| `name` | no | `string` | Optional ontology display name. Applies only to source_format=ntriples. |
| `materialize_graph` | no | `boolean` | For N-Triples imports, also materialize object triples into graph entities/relations. Keep false for pure ontology registration. |
| `force` | no | `boolean` | Compatibility flag for native CLI fallback only: allow import even when MindBrain reports an active writer session. Native HTTP imports always use the serialized writer lane. |

### `ghostcrab_pack`

Read. Build a compact working-memory pack from active projections plus top matching facts for a query.

| Field | Value |
|-------|-------|
| Visibility | basic |
| Subsystem | pragma |
| Access | read |
| Required arguments | `query` |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `query` | yes | `string` | - |
| `agent_id` | no | `string` | - |
| `scope` | no | `string` | - |
| `limit` | no | `integer` | - |
| `workspace_id` | no | `string` | Target workspace id. Overrides session context for this call only. |
| `schema_id` | no | `string` | Schema filter for facts retrieval. Overrides session schema_id for this call only. |

### `ghostcrab_project`

Model. Create or refresh compact provisional projections and working scopes after the user request is clear enough to model, without freezing a schema. Do not initialize a provisional scope on the first fuzzy onboarding turn. Prefer one compact projection over many overlapping projections.

| Field | Value |
|-------|-------|
| Visibility | basic |
| Subsystem | pragma |
| Access | model |
| Required arguments | `scope`, `content` |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `scope` | yes | `string` | - |
| `content` | yes | `string` | - |
| `proj_type` | no | `string` | - |
| `status` | no | `string` | - |
| `weight` | no | `number` | - |
| `activity_family` | no | `string` | - |
| `agent_id` | no | `string` | - |
| `provisional` | no | `boolean` | - |

### `ghostcrab_projection_get`

Read. Retrieve a materialized graph projection by projection_id from ProjectionResult entities, optionally including linked evidence and DeltaFinding rows.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | pragma |
| Access | model |
| Required arguments | `projection_id` |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `workspace_id` | no | `string` | Target workspace id. Overrides session context for this call only. |
| `collection_id` | no | `string\|null` | Optional collection scope. Omit or pass null to search all collections in the workspace. |
| `projection_id` | yes | `string` | Projection identifier stored in graph_entity.metadata_json.projection_id. |
| `include_evidence` | no | `boolean` | Include graph_relation rows sourced from ProjectionResult and their target evidence entities. |
| `include_deltas` | no | `boolean` | Include DeltaFinding entities where metadata_json.metric equals projection_id. |

### `ghostcrab_projections_list`

Read. Catalogue discoverable projections for a workspace before reading content. Sources: (1) mindbrain_answer_artifacts registry — analysis_plan, live_answer_view, answer_snapshot; (2) optional graph scan — distinct projection_id on ProjectionResult entities when include_graph is true. Returns projections[] with public_label (user-facing), artifact_id, projection_id, artifact_kind, legacy_kind, source (registry|graph), and suggested_tools. Routing: analysis_plan → ghostcrab_artifact_get, ghostcrab_pack; live_answer_view → ghostcrab_artifact_get, ghostcrab_live_refresh; answer_snapshot or graph → ghostcrab_projection_get. Does not return pack rows, payloads, or graph evidence. kind filter: analysis_plan | live_answer_view | answer_snapshot | graph. With kind analysis_plan or live_answer_view, graph scan is skipped. Operator doc: docs/reference/projections-discovery.md.

Extended guide: [projections-discovery.md](projections-discovery.md).

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | pragma |
| Access | read |
| Required arguments | none |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `workspace_id` | no | `string` | Target workspace id. Defaults to the active MCP session workspace. Required when the session has no pinned workspace. |
| `kind` | no | `string` | Optional filter. analysis_plan \| live_answer_view \| answer_snapshot limit registry rows; graph lists only ProjectionResult projection_id values. Omit for all registry kinds plus optional graph append. |
| `agent_id` | no | `string` | Optional registry filter — mainly analysis_plan rows bound to an agent (e.g. agent:self). |
| `scope` | no | `string` | Optional registry filter on artifact scope (often equals workspace id for analysis plans). |
| `include_graph` | no | `boolean` | When true, append graph ProjectionResult projection_id values not already listed. Ignored when kind is analysis_plan or live_answer_view. |
| `limit` | no | `integer` | Maximum rows per source (registry SQL and graph SQL each apply this limit). |

### `ghostcrab_quality_convergence_get`

Read. Retrieve one persisted MindBrain quality convergence report by run_id.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | graph |
| Access | read |
| Required arguments | `run_id` |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `run_id` | yes | `string` | - |

### `ghostcrab_quality_convergence_list`

Read. List persisted MindBrain quality convergence runs for a workspace.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | graph |
| Access | read |
| Required arguments | none |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `workspace_id` | no | `string` | - |
| `limit` | no | `integer` | - |

### `ghostcrab_quality_convergence_run`

Read/write. Run the native MindBrain quality convergence pipeline for a workspace. Persists the run and proposed remediation actions by default; set persist:false for a read-only preview.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | graph |
| Access | write |
| Required arguments | none |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `workspace_id` | no | `string` | Target workspace id. Defaults to the current MCP session workspace. |
| `ontology_id` | no | `string` | Optional ontology id. When omitted, MindBrain uses the workspace default ontology. |
| `persist` | no | `boolean` | Persist the convergence run and remediation actions in MindBrain. |
| `limit` | no | `integer` | Maximum graph diagnostic issue rows considered. |
| `component_small_max` | no | `integer` | Weak connected components with this many nodes or fewer are reported as small components. |

### `ghostcrab_quality_remediation_actions`

Read. List remediation actions proposed by a persisted MindBrain quality convergence run.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | graph |
| Access | read |
| Required arguments | `run_id` |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `run_id` | yes | `string` | - |
| `status` | no | `string` | - |

### `ghostcrab_quality_remediation_apply`

Write. Apply one approved allow-listed remediation action. V1 only executes diagnostic-only graph diagnostics actions and records the result.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | graph |
| Access | write |
| Required arguments | `run_id`, `action_id` |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `run_id` | yes | `string` | - |
| `action_id` | yes | `string` | - |
| `actor` | no | `string` | - |

### `ghostcrab_quality_remediation_decide`

Write. Approve or reject a proposed MindBrain quality remediation action. Approval records intent only; execution is separate.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | graph |
| Access | write |
| Required arguments | `action_id`, `decision` |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `action_id` | yes | `string` | - |
| `decision` | yes | `string` | - |
| `actor` | no | `string` | - |
| `note` | no | `string` | - |

### `ghostcrab_reindex_all`

Write. Rebuild all derived indexes for a workspace: every registered collection (BM25, facet postings, graph via MindBrain reindexAll) plus agent_facts FTS bootstrap by default. Use scope graph|collections|all to limit work.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | facets |
| Access | write |
| Required arguments | none |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `workspace_id` | no | `string` | Target workspace id. Overrides session context for this call only. |
| `document_table_id` | no | `integer` | Optional facet table_id for graph entity-document projection when running graph-only fallback (no discoverable collections). |
| `include_agent_facts` | no | `boolean` | When true, run agent_facts FTS bootstrap (ensureFactsFtsSync) after collection reindex. |
| `scope` | no | `string` | all: collections loop + agent_facts FTS; collections: per-collection reindexAll only; graph: workspace graph reindex only. |

### `ghostcrab_remember`

Write. Store durable facts, stable notes, or observations in persistent memory. Call ghostcrab_status first for routing and workspace guidance when not on first-turn fuzzy onboarding. Do not use on a first-turn fuzzy onboarding request. Summarize before storing; avoid using raw payloads as the durable artifact when a stable summary will do.

| Field | Value |
|-------|-------|
| Visibility | basic |
| Subsystem | facets |
| Access | write |
| Required arguments | `content` |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `content` | yes | `string` | Content to store in the facets store. |
| `facets` | no | `object` | Facet metadata for later filtering. |
| `schema_id` | no | `string` | - |
| `workspace_id` | no | `string` | Target workspace id. Overrides session context for this call only. |
| `created_by` | no | `string` | - |
| `valid_until` | no | `string` | Optional expiry date in YYYY-MM-DD format. |

### `ghostcrab_schema_get`

Read. Return the raw registered schema definition from the MCP schema registry only. Does not inspect native ontology_* tables or compute sync status.

| Field | Value |
|-------|-------|
| Visibility | basic |
| Subsystem | facets |
| Access | read |
| Required arguments | `schema_id` |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `schema_id` | yes | `string` | - |
| `workspace_id` | no | `string` | Target workspace id. Defaults to the current MCP session workspace. |

### `ghostcrab_schema_inspect`

Inspect a registered schema by its schema_id.

| Field | Value |
|-------|-------|
| Visibility | basic |
| Subsystem | facets |
| Access | read |
| Required arguments | `schema_id` |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `schema_id` | yes | `string` | - |

### `ghostcrab_schema_list`

Read. List registered schemas. Use 'domain' to filter by namespace prefix and 'summary_only' to avoid a full definition dump.

| Field | Value |
|-------|-------|
| Visibility | basic |
| Subsystem | facets |
| Access | read |
| Required arguments | none |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `target` | no | `string` | - |
| `domain` | no | `string` | Filter by schema_id namespace prefix (part before ':'). Example: 'ghostcrab'. |
| `summary_only` | no | `boolean` | When true, return only schema_id, description, target, and version. |

### `ghostcrab_schema_register`

Write. Freeze-level action: register a facet schema, graph node type, or edge label in the self-describing schema store. Never call on a first-turn fuzzy onboarding request. Only register a canonical or custom schema after a confirmed modeling gap and explicit user confirmation.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | facets |
| Access | write |
| Required arguments | `definition` |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `target` | no | `string` | - |
| `workspace_id` | no | `string` | Target workspace id. Overrides session context for this call only. |
| `definition` | yes | `object` | Nested schema document. Put schema_id and description here only — do not place schema_id at the payload root next to target (Zod expects schema_id inside definition). Additional keys (e.g. facets, field specs) are accepted and stored with the definition (passthrough). |

### `ghostcrab_schema_sync_apply`

Write. Apply an explicitly confirmed schema synchronization action between the MCP schema registry and native ontology_* tables. Arbitrary schema packs still require LinkML/native ontology import.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | facets |
| Access | write |
| Required arguments | `schema_id`, `action`, `confirm` |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `schema_id` | yes | `string` | - |
| `workspace_id` | no | `string` | Target workspace id. Defaults to the current MCP session workspace. |
| `action` | yes | `string` | - |
| `confirm` | yes | `boolean` | Must be true to mutate the registry projection. |

### `ghostcrab_schema_sync_preview`

Read. Preview registry/native ontology synchronization actions for a schema_id without mutating either store.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | facets |
| Access | read |
| Required arguments | `schema_id` |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `schema_id` | yes | `string` | - |
| `workspace_id` | no | `string` | Target workspace id. Defaults to the current MCP session workspace. |

### `ghostcrab_search`

Read. Retrieve ranked facts from persistent memory using keyword search and exact facet filters. Prefer explicit schema_id and exact filters before broad free-text search. One zero-result exact read does not prove the whole domain is empty. On a first-turn fuzzy GhostCrab onboarding request, do not use this tool for broad surface exploration unless the user explicitly asked about available models or schema inventory.

| Field | Value |
|-------|-------|
| Visibility | basic |
| Subsystem | facets |
| Access | read |
| Required arguments | none |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `query` | no | `string` | Keyword query. Empty string means pure facet filtering. |
| `filters` | no | `object` | Exact facet filters. Arrays are treated as OR. Keys are facet field names; values are strings, numbers, booleans, or arrays for OR. |
| `limit` | no | `integer` | Maximum number of rows to return. |
| `mode` | no | `string` | - |
| `schema_id` | no | `string` | Optional schema filter. Overrides session schema_id for this call only. |
| `workspace_id` | no | `string` | Target workspace id. Overrides session context for this call only. |

### `ghostcrab_status`

Bootstrap — call first for normal work. On first-turn fuzzy GhostCrab onboarding, do not call unless the user explicitly asked about readiness, available surfaces, or runtime health. Returns routing, autonomy policies, activity families, and runtime diagnostics. Prefer calling only when health, autonomy, or global blockers may materially affect the answer; do not surface backend-health commentary unless it changes the user-visible answer.

| Field | Value |
|-------|-------|
| Visibility | basic |
| Subsystem | pragma |
| Access | bootstrap |
| Required arguments | none |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `agent_id` | no | `string` | - |

### `ghostcrab_tool_search`

Read. Search the full GhostCrab tool catalog by tool name, description, argument names, and argument descriptions. Use this when the default tool list is too small or when you need to discover specialized workspace, ontology, loadout, or graph tools.

| Field | Value |
|-------|-------|
| Visibility | basic |
| Subsystem | facets |
| Access | read |
| Required arguments | none |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `query` | no | `string` | Natural-language or keyword query over tool names, descriptions, and argument documentation. Empty string means faceted browsing only. |
| `limit` | no | `integer` | Maximum number of tools to return. |
| `access` | no | `array` | Optional access facet filter: bootstrap, read, write, model, guide, or session. |
| `subsystem` | no | `array` | Optional subsystem facet filter: facets, graph, workspace, ontology, loadout, pragma, or session. |
| `visibility` | no | `array` | Optional visibility facet filter. 'basic' matches the compact default list; 'extended' matches hidden-by-default tools. |
| `name_prefix` | no | `string` | Optional tool-name prefix filter, for example 'ghostcrab_workspace_' or 'ghostcrab_ontology_'. |
| `include_input_schema` | no | `boolean` | When true, include each matching tool's full MCP inputSchema in the results. |

### `ghostcrab_traverse`

Traverse the directed knowledge graph from a start node and return the discovered path.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | graph |
| Access | read |
| Required arguments | `start` |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `start` | yes | `string` | - |
| `direction` | no | `string` | - |
| `edge_labels` | no | `array` | - |
| `depth` | no | `integer` | - |
| `target` | no | `string` | - |
| `workspace_id` | no | `string` | Target workspace id. Overrides session context for this call only. |

### `ghostcrab_upsert`

Write. Update current-state facts in place by exact match, or create if missing. Read before writing. Before replacing meaningful tracker state, preserve transition rationale when losing it would hurt recovery. Do not use on a first-turn fuzzy onboarding request. match uses match.id (row UUID) and/or match.facets; facet selectors must live under match.facets, not at the root of match (wrong: {"match":{"label":"X"}}; right: {"match":{"facets":{"label":"X"}}}). Prefer a stable record_id in match.facets over labels that may change. When create_if_missing is true and no row matches, set_content is required for the new row.

| Field | Value |
|-------|-------|
| Visibility | basic |
| Subsystem | facets |
| Access | write |
| Required arguments | `schema_id`, `match` |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `schema_id` | yes | `string` | Logical record family to update. |
| `workspace_id` | no | `string` | Target workspace id. Overrides session context for this call only. |
| `match` | yes | `object` | Exact match selector. Must include at least one of: id (row UUID from a prior write) or facets (non-empty object). All facet keys used for matching must appear under match.facets — do not put them at the root of match (e.g. use {"facets":{"label":"Deal A"}} not {"label":"Deal A"}). Multiple facet entries are ANDed via JSONB containment. |
| `set_content` | no | `string` | Replacement content for the current-state record. |
| `set_facets` | no | `object` | Facet keys to merge into the current-state record. New keys overwrite old keys. |
| `created_by` | no | `string` | Optional actor label for the update or create operation. |
| `valid_until` | no | `string\|null` | Optional expiry date in YYYY-MM-DD format, or null to clear it. |
| `create_if_missing` | no | `boolean` | When true, create the record if no exact match exists. |

### `ghostcrab_workspace_create`

Create a new logical workspace that scopes facets, entities, and DDL migrations. Idempotent: re-creating an existing workspace with the same id is a no-op.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | workspace |
| Access | write |
| Required arguments | `id`, `label` |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `id` | yes | `string` | Workspace identifier: lowercase alphanum + hyphens, 2–64 chars, must start with a letter. Example: 'prod-eu', 'research-q1'. |
| `label` | yes | `string` | Human-readable name for the workspace. |
| `description` | no | `string` | Optional longer description of the workspace purpose. |
| `created_by` | no | `string` | Identity of the requester (agent name, user email, etc.). |

### `ghostcrab_workspace_delete`

Write. Delete a workspace: wipe scoped data, then remove the workspace row (mode=hard) or mark it archived (mode=soft). Refuses the default workspace.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | workspace |
| Access | write |
| Required arguments | `workspace_id`, `confirm` |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `workspace_id` | yes | `string` | Target workspace id to delete. |
| `confirm` | yes | `boolean` | Must be true to confirm destructive delete. |
| `mode` | no | `string` | hard removes the workspace row after reset; soft archives it. |

### `ghostcrab_workspace_export_model`

Export workspace semantic model as a public 1.0.0 JSON contract for synthetic data generators. Includes workspace metadata, table/column/relation semantics, generation_hints, and validation_warnings.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | workspace |
| Access | read |
| Required arguments | `workspace_id` |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `workspace_id` | yes | `string` | Target workspace id. |
| `depth` | no | `string` | Export granularity: tables_only, tables_and_columns (default), or full (includes relations). |

### `ghostcrab_workspace_export_model_toon`

Export workspace semantic model as TOON generated by the Zig standalone engine.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | workspace |
| Access | read |
| Required arguments | `workspace_id` |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `workspace_id` | yes | `string` | Target workspace id. |

### `ghostcrab_workspace_inspect`

Inspect stored workspace semantics (table_semantics, column_semantics, relation_semantics) for a workspace. Optional filter by table name.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | workspace |
| Access | read |
| Required arguments | `workspace_id` |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `workspace_id` | yes | `string` | Target workspace id. |
| `table_name` | no | `string` | If set, restrict to rows where table_name matches (case-sensitive substring on table_semantics; prefix match on column/relation tables). |
| `include_columns` | no | `boolean` | Include column_semantics rows (default true). |
| `include_relations` | no | `boolean` | Include relation_semantics rows (default true). |

### `ghostcrab_workspace_list`

List all MindBrain workspace_ids in this database with live statistics. Call before switching workspace context; echo the chosen workspace_id to the user when changing context.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | workspace |
| Access | read |
| Required arguments | none |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `status` | no | `string` | Optional filter by workspace status. Omit to return all. |

### `ghostcrab_workspace_reset`

Write. Wipe all data scoped to a workspace (facets, graph, raw imports, semantics, pending migrations, projections) without deleting the workspace metadata row. Idempotent. Refuses the default workspace.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | workspace |
| Access | write |
| Required arguments | `workspace_id`, `confirm` |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `workspace_id` | yes | `string` | Target workspace id to reset. |
| `confirm` | yes | `boolean` | Must be true to confirm destructive reset. |

### `ghostcrab_workspace_use`

Set the active MindBrain workspace_id and/or schema filter for this MCP server session. Use when the user asked to work in another workspace or after ghostcrab_workspace_list and confirming the target — announce the switch to the user. Do not call reactively on empty reads or tool errors. All subsequent tool calls use these defaults unless they pass explicit workspace_id / schema_id overrides. Session context is shared across all chats in the same MCP server process.

| Field | Value |
|-------|-------|
| Visibility | extended |
| Subsystem | session |
| Access | session |
| Required arguments | none |

| Argument | Required | Type | Description |
|----------|----------|------|-------------|
| `workspace_id` | no | `string` | Workspace id to activate for this session. Omit to keep the current workspace_id unchanged. |
| `schema_id` | no | `string\|null` | Schema filter to activate (e.g. 'ghostcrab:task'). Pass null to clear the schema filter. Omit to keep the current schema_id unchanged. |
