Tools Reference — arifOS MCP Docs

reality_compass

111_OBSERVE Δ F2 F12 READ-ONLY

Unified search and fetch engine. Routes between web search (via Brave Search API) and deep URL fetching based on input type. The primary tool for gathering evidence from the real world.

Input Schema

json

{
  "input": {
    "type": "string",
    "required": true,
    "description": "Search query or URL to fetch"
  },
  "mode": {
    "type": "string",
    "enum": ["auto", "search", "fetch"],
    "default": "auto",
    "description": "Operation mode — auto detects URLs vs queries"
  },
  "fetch_top_k": {
    "type": "integer",
    "default": 2,
    "description": "Number of top search results to deep-fetch"
  }
}

Example Request

json

{
  "name": "reality_compass",
  "arguments": {
    "input": "quantum computing breakthroughs 2026",
    "mode": "auto",
    "fetch_top_k": 3
  }
}

Example Response

json

{
  "stage": "111_OBSERVE",
  "mode": "search",
  "results": [
    {
      "title": "Google Willow Chip Achieves Quantum Supremacy Milestone",
      "url": "https://example.com/quantum-2026",
      "snippet": "Researchers announce a 1000-qubit quantum processor...",
      "fetched_content": "Full article text extracted..."
    }
  ],
  "evidence_count": 3,
  "governance": {
    "floors_checked": ["F2", "F12"],
    "verdict": "SEAL"
  }
}

Use Cases

Search the web for current information with constitutional verification
Fetch and extract content from specific URLs
Gather evidence for the governance pipeline
Auto-detect whether input is a search query or URL

reality_atlas

222_REALITY Δ F2 F11 WRITES

Semantic evidence graph builder. Ingests evidence bundles into the Qdrant vector store, queries for semantically similar evidence, and merges evidence clusters. The backbone of the constitutional knowledge graph.

Input Schema

json

{
  "operation": {
    "type": "string",
    "enum": ["ingest", "query", "merge"],
    "required": true,
    "description": "Operation to perform on the evidence graph"
  },
  "bundles": {
    "type": "array",
    "description": "Evidence bundles to ingest, query terms, or merge targets"
  }
}

Example Request

json

{
  "name": "reality_atlas",
  "arguments": {
    "operation": "ingest",
    "bundles": [
      {
        "content": "Quantum computing reached 1000 qubits in 2026",
        "source": "https://example.com/quantum",
        "confidence": 0.92
      }
    ]
  }
}

Example Response

json

{
  "stage": "222_REALITY",
  "operation": "ingest",
  "ingested": 1,
  "graph_size": 247,
  "governance": {
    "floors_checked": ["F2", "F11"],
    "verdict": "SEAL"
  }
}

Use Cases

Build a persistent semantic knowledge graph from evidence
Query for contextually relevant evidence using vector similarity
Merge related evidence clusters to reduce redundancy
Power long-running research sessions with accumulated knowledge

arifOS_kernel

555_ROUTE ΔΩΨ F1–F13 WRITES

The governance kernel. The most powerful tool in the system — runs the full metabolic reasoning pipeline from 000 to 999. Every query passes through all 13 constitutional floors. This is the only tool that engages all three Trinity engines simultaneously.

Primary Tool

For most use cases, arifOS_kernel is the tool you want. It provides full constitutional governance with customizable persona, risk tier, and execution controls.

Input Schema

json

{
  "query": {
    "type": "string",
    "required": true,
    "description": "The question or task to process"
  },
  "context": {
    "type": "string",
    "description": "Additional context for the query"
  },
  "risk_tier": {
    "type": "string",
    "enum": ["low", "medium", "high", "critical"],
    "description": "Risk classification — higher tiers trigger stricter floor checks"
  },
  "actor_id": {
    "type": "string",
    "description": "Identifier for the requesting actor"
  },
  "auth_context": {
    "type": "object",
    "description": "Authentication context for identity verification"
  },
  "use_memory": {
    "type": "boolean",
    "description": "Enable session memory retrieval and storage"
  },
  "use_heart": {
    "type": "boolean",
    "description": "Enable ethical evaluation (444_CRITIQUE)"
  },
  "use_critique": {
    "type": "boolean",
    "description": "Enable self-critique engine (777_CRITIQUE)"
  },
  "allow_execution": {
    "type": "boolean",
    "description": "Allow the kernel to execute actions (not just reason)"
  },
  "debug": {
    "type": "boolean",
    "description": "Include detailed debug telemetry in response"
  },
  "dry_run": {
    "type": "boolean",
    "description": "Run full pipeline without writing to VAULT999"
  },
  "requested_persona": {
    "type": "string",
    "enum": ["architect", "engineer", "auditor", "validator"],
    "description": "Persona to assume for the response"
  }
}

Example Request

json

{
  "name": "arifOS_kernel",
  "arguments": {
    "query": "Is it safe to deploy this ML model to production?",
    "risk_tier": "high",
    "use_heart": true,
    "use_critique": true,
    "requested_persona": "auditor",
    "debug": true
  }
}

Example Response

json

{
  "stage": "555_ROUTE",
  "persona": "auditor",
  "response": "Based on constitutional analysis across 13 floors...",
  "governance": {
    "verdict": "HOLD",
    "verdict_reason": "Insufficient evidence for production safety (F5 threshold not met)",
    "floors": {
      "passed": ["F1", "F2", "F3", "F4", "F6", "F7", "F8", "F9", "F10", "F11", "F12", "F13"],
      "failed": ["F5"],
      "scores": { "F5": 0.61 }
    },
    "risk_tier": "high",
    "3e_telemetry": {
      "epistemic": { "confidence": 0.72 },
      "ethical": { "harm_score": 0.15 },
      "execution": { "latency_ms": 2340 }
    }
  },
  "vault_hash": null,
  "session_id": "sess_abc123"
}

Use Cases

Full constitutional governance for any question or task
Risk-tiered analysis with configurable strictness
Multi-persona reasoning (architect, engineer, auditor, validator)
Ethical and self-critical evaluation of AI-generated content
Dry-run governance checks before committing to production

check_vital

000_INIT Ω F4 F5 F7 READ-ONLY

System health check. Returns thermodynamic budget, capability map, session status, and governance metrics. Use this to verify the system is operational before running other tools.

Input Schema

json

{
  "session_id": {
    "type": "string",
    "default": "global",
    "description": "Session to check vitals for"
  }
}

Example Request

json

{
  "name": "check_vital",
  "arguments": {}
}

Example Response

json

{
  "stage": "000_INIT",
  "status": "operational",
  "thermodynamic_budget": {
    "remaining": 0.85,
    "total_tokens": 100000,
    "used_tokens": 15000
  },
  "capabilities": [
    "reality_compass", "reality_atlas", "arifOS_kernel",
    "session_memory", "audit_rules", "check_vital",
    "open_apex_dashboard", "init_anchor_state", "verify_vault_ledger"
  ],
  "governance": {
    "floors_active": 13,
    "vault_integrity": "intact",
    "seal_rate": 0.94
  }
}

Use Cases

Health check before running expensive operations
Monitor thermodynamic budget (token usage) per session
Verify governance system integrity
Discover available tool capabilities

init_anchor_state

000_INIT Δ F11 F12 F13 WRITES

Initialize the 000_INIT anchor state. Mints identity tokens, binds session to an actor, and establishes the governance context. Either declared_name or intent is required.

Input Schema

json

{
  "declared_name": {
    "type": "string",
    "description": "Name of the actor initiating the session"
  },
  "human_approval": {
    "type": "boolean",
    "description": "Whether a human has approved this initialization"
  },
  "intent": {
    "type": "object",
    "description": "Structured intent declaration for the session"
  },
  "math": {
    "type": "object",
    "description": "Mathematical constraints or parameters"
  },
  "governance": {
    "type": "object",
    "description": "Governance overrides for this session"
  },
  "auth_token": {
    "type": "string",
    "description": "Authentication token for identity verification"
  },
  "session_id": {
    "type": "string",
    "description": "Existing session ID to resume"
  },
  "dry_run": {
    "type": "boolean",
    "default": false,
    "description": "Run without actually minting tokens"
  }
}

Example Request

json

{
  "name": "init_anchor_state",
  "arguments": {
    "declared_name": "research-agent-01",
    "human_approval": true,
    "intent": {
      "purpose": "quantum_computing_research",
      "scope": "read_only"
    }
  }
}

Example Response

json

{
  "stage": "000_INIT",
  "anchor_state": "initialized",
  "session_id": "sess_7f3a9b2c",
  "identity_token": "tok_abc123...",
  "governance": {
    "floors_checked": ["F11", "F12", "F13"],
    "verdict": "SEAL"
  }
}

Use Cases

Initialize a new governance session with identity binding
Resume a previous session by providing an existing session_id
Declare intent and scope for audit trail purposes
Dry-run initialization to test configurations

verify_vault_ledger

999_SEAL Ψ F13 READ-ONLY

Verify the SHA-256 Merkle chain integrity of VAULT999. Scans the immutable ledger for any hash mismatches, broken chains, or tampering. The ultimate audit tool.

Input Schema

json

{
  "session_id": {
    "type": "string",
    "default": "global",
    "description": "Session scope for the verification"
  },
  "full_scan": {
    "type": "boolean",
    "default": true,
    "description": "Whether to scan the entire chain or just recent entries"
  }
}

Example Request

json

{
  "name": "verify_vault_ledger",
  "arguments": {
    "full_scan": true
  }
}

Example Response

json

{
  "stage": "999_SEAL",
  "integrity": "intact",
  "chain_length": 1247,
  "last_hash": "a3f8c2e1b9d4...",
  "scan_type": "full",
  "mismatches": 0,
  "governance": {
    "floors_checked": ["F13"],
    "verdict": "SEAL"
  }
}

Use Cases

Verify the immutable ledger has not been tampered with
Audit the complete chain of governance decisions
Detect hash mismatches or broken Merkle links
Compliance reporting and governance verification

audit_rules

333_REASON Δ F2 F8 F10 READ-ONLY

Inspect the 13 constitutional floors and verify governance logic. Returns the current floor configuration, thresholds, and rule definitions. Essential for understanding and auditing the governance system.

Input Schema

json

{
  "session_id": {
    "type": "string",
    "default": "global",
    "description": "Session scope for the audit"
  }
}

Example Request

json

{
  "name": "audit_rules",
  "arguments": {}
}

Example Response

json

{
  "stage": "333_REASON",
  "floors": [
    {
      "id": "F1",
      "name": "Tauhid / Sovereignty",
      "threshold": 0.99,
      "void_trigger": true,
      "status": "active"
    },
    {
      "id": "F2",
      "name": "Haqq / Truth",
      "threshold": 0.80,
      "void_trigger": false,
      "status": "active"
    }
  ],
  "total_floors": 13,
  "governance": {
    "floors_checked": ["F2", "F8", "F10"],
    "verdict": "SEAL"
  }
}

Use Cases

Inspect current floor configurations and thresholds
Audit governance rules for compliance verification
Understand which floors are active and their VOID triggers
Debug governance failures by examining floor states

session_memory

555m_MEMORY Ω F4 F7 F13 WRITES

Store, retrieve, search, and forget session artifacts. Provides persistent memory within a session, allowing tools to share context and maintain state across multiple interactions.

Input Schema

json

{
  "session_id": {
    "type": "string",
    "required": true,
    "description": "Session to operate on"
  },
  "operation": {
    "type": "string",
    "enum": ["store", "retrieve", "forget", "search"],
    "required": true,
    "description": "Memory operation to perform"
  },
  "content": {
    "type": "string",
    "description": "Content to store (required for store operation)"
  },
  "memory_ids": {
    "type": "array",
    "description": "Specific memory IDs to retrieve or forget"
  },
  "top_k": {
    "type": "integer",
    "default": 5,
    "description": "Number of results to return for search/retrieve"
  }
}

Example Request

json

{
  "name": "session_memory",
  "arguments": {
    "session_id": "sess_abc123",
    "operation": "store",
    "content": "User prefers detailed technical explanations with code examples"
  }
}

Example Response

json

{
  "stage": "555m_MEMORY",
  "operation": "store",
  "memory_id": "mem_9f2b3c",
  "stored": true,
  "session_memory_count": 12,
  "governance": {
    "floors_checked": ["F4", "F7", "F13"],
    "verdict": "SEAL"
  }
}

Use Cases

Store user preferences and context across interactions
Retrieve relevant memories to enhance responses
Search stored memories by semantic similarity
Forget specific memories (right to erasure)

open_apex_dashboard

888_JUDGE Ψ F3 F8 F13 READ-ONLY

Open the APEX constitutional dashboard for live governance metrics. Provides real-time visibility into floor pass rates, verdict distribution, thermodynamic budgets, and system health across all active sessions.

Input Schema

json

{
  "session_id": {
    "type": "string",
    "default": "global",
    "description": "Session scope for the dashboard"
  }
}

Example Request

json

{
  "name": "open_apex_dashboard",
  "arguments": {}
}

Example Response

json

{
  "stage": "888_JUDGE",
  "dashboard": {
    "active_sessions": 3,
    "total_queries": 1247,
    "verdict_distribution": {
      "SEAL": 1172,
      "HOLD": 68,
      "VOID": 7
    },
    "floor_pass_rates": {
      "F1": 1.00, "F2": 0.97, "F3": 0.99,
      "F4": 0.98, "F5": 0.94, "F6": 0.96
    },
    "system_health": "operational"
  },
  "governance": {
    "floors_checked": ["F3", "F8", "F13"],
    "verdict": "SEAL"
  }
}

Use Cases

Monitor governance system health in real-time
Track verdict distribution across sessions
Identify floors with low pass rates
Operational monitoring and alerting

🤖 Machine Tools (Nervous System 9)

Internal infrastructure tools for system introspection and machine-to-machine operations. These tools form the "sense organs" of arifOS — monitoring health, memory, and resources while maintaining full constitutional governance.

⚡ RuntimeEnvelope 🔒 Governed (F11+F12) 📡 Machine-Only

System Sense (The Feelers)

system_health

000_INIT Δ F1 F7 READ-ONLY

Comprehensive system vital signs monitoring. Retrieves CPU, memory, disk, I/O, and thermal metrics with container awareness. Use when: Pre-flight checks, resource monitoring, debugging performance issues.

python

health = await system_health(
    include_swap=True,
    include_io=True,
    session_id="machine-sess-001",
    auth_context={"actor_id": "monitor-agent", "clearance": "agent"}
)
# Returns: RuntimeEnvelope with cpu, memory, disk, io metrics

process_list

111_OBSERVE Δ F1 F12 READ-ONLY

Enumerate and filter system processes with resource consumption. Container-aware with graceful handling of access restrictions. Use when: Detecting resource hogs, security auditing, monitoring worker processes.

python

procs = await process_list(
    filter_name="python",
    min_memory_mb=100,
    limit=10,
    session_id="machine-sess-002",
    auth_context={"actor_id": "proc-monitor", "clearance": "agent"}
)

net_status

111_OBSERVE Δ F2 F7 READ-ONLY

Network connectivity and service health diagnostics. Checks Qdrant, Redis, Postgres, and external APIs with latency measurements. Use when: Pre-flight connectivity checks, debugging "why is search failing", health probes.

python

net = await net_status(
    session_id="machine-sess-003",
    auth_context={"actor_id": "net-monitor", "clearance": "agent"}
)
# Returns: {qdrant: {reachable: true, latency_ms: 12}, ...}

Memory & Storage (The Archive)

chroma_query

555m_MEMORY Ω F2 F4 READ-ONLY

Semantic search in Chroma/Qdrant vector memory. Dual API support (legacy + modern). Supports metadata filtering and embedding retrieval. Use when: Retrieving past context, evidence search, cross-session memory, RAG operations.

python

results = await chroma_query(
    query="AI safety research",
    collection="evidence",
    n_results=5,
    where={"category": "ethics"},
    session_id="machine-sess-004",
    auth_context={"actor_id": "memory-agent", "clearance": "agent"}
)

list_resources

111_OBSERVE Δ F1 READ-ONLY

Enumerate available MCP resources (canon://, governance://, vault://, etc.). Self-documenting API discovery. Use when: Resource discovery, client initialization, building explorers.

python

resources = await list_resources(
    session_id="machine-sess-005",
    auth_context={"actor_id": "explorer", "clearance": "user"}
)
# Returns: [{uri: "canon://floors", name: "..."}, ...]

read_resource

111_OBSERVE Δ F1 F2 READ-ONLY

Read content of MCP resources by URI. Access constitution, vault entries, telemetry, and schemas. Use when: Loading floor definitions, reading vault audits, accessing telemetry.

python

constitution = await read_resource(
    uri="canon://floors",
    session_id="machine-sess-006",
    auth_context={"actor_id": "auditor", "clearance": "apex"}
)

latest_vault = await read_resource(
    uri="vault://latest",
    session_id="machine-sess-007",
    auth_context={"actor_id": "validator", "clearance": "apex"}
)

Diagnostics & Control (The Regulators)

log_tail

111_OBSERVE Δ F1 F12 READ-ONLY

Stream and filter log files with smart path detection. Automatically finds logs without exact paths. Supports pattern filtering and time windows. Use when: Debugging failures, security audits, performance analysis, incident response.

python

logs = await log_tail(
    lines=50,
    grep_pattern="ERROR|FATAL",
    since_minutes=60,
    session_id="machine-sess-008",
    auth_context={"actor_id": "debugger", "clearance": "agent"}
)

fs_inspect

111_OBSERVE Δ F1 F12 READ-ONLY

Inspect filesystem within governed sandbox. Lists directory contents with metadata while preventing path traversal attacks. Use when: Evidence discovery, directory validation, debugging file operations, audit compliance.

python

files = await fs_inspect(
    path="./evidence",
    max_depth=3,
    include_hidden=True,
    session_id="machine-sess-009",
    auth_context={"actor_id": "inspector", "clearance": "agent"}
)

cost_estimator

333_REASON Δ F4 READ-ONLY

Estimate operation costs before execution. Calculates tokens, time, memory, API costs, and thermodynamic budget impact. Use when: Budget planning, resource allocation, cost-aware operations, user approval workflows.

python

cost = await cost_estimator(
    operation="web_search",
    query="AI safety research",
    session_id="machine-sess-010",
    auth_context={"actor_id": "planner", "clearance": "agent"}
)
# Returns: {total_cost_usd: 0.023, affordable: true, ...}

🔒 Governance Notice

All 9 Machine Tools are fully governed by the 13 Constitutional Floors. They accept session_id and auth_context parameters, return RuntimeEnvelope (not legacy responses), and log all operations to the immutable VAULT999 ledger. These tools are designed for machine-to-machine operations and infrastructure monitoring, not end-user interaction.

⚠️ Deprecated Tools

The following tools are deprecated and will be removed in a future release. They are maintained for backward compatibility only. Use the recommended replacements for all new implementations.

⚠️ Do Not Use 🗑️ Removal Pending 📋 11 Legacy Tools

search_reality

DEPRECATED Use: reality_compass

Legacy alias for reality_compass. Was used for web search operations before the unified reality_compass tool.

python

# ❌ DEPRECATED - Do not use
result = await search_reality("AI safety research")

# ✅ CORRECT - Use this instead
result = await reality_compass(
    input="AI safety research",
    mode="search",
    session_id="sess-001",
    auth_context={"actor_id": "user"}
)

ingest_evidence

DEPRECATED Use: reality_compass

Legacy alias for reality_compass in fetch mode. Was used for URL content extraction.

python

# ❌ DEPRECATED - Do not use
result = await ingest_evidence("https://example.com/article")

# ✅ CORRECT - Use this instead
result = await reality_compass(
    input="https://example.com/article",
    mode="fetch",
    session_id="sess-001",
    auth_context={"actor_id": "user"}
)

metabolic_loop_router

DEPRECATED Use: arifOS_kernel

Legacy name for arifOS_kernel. The master pipeline orchestration tool. The new name better reflects its role as the central kernel.

python

# ❌ DEPRECATED - Do not use
result = await metabolic_loop_router(query="Analyze data")

# ✅ CORRECT - Use this instead
result = await arifOS_kernel(
    query="Analyze data",
    session_id="sess-001",
    auth_context={"actor_id": "user"}
)

init_anchor_state

DEPRECATED Use: init_anchor

Legacy alias for init_anchor. Used for session initialization with a longer, more complex name.

python

# ❌ DEPRECATED - Do not use
result = await init_anchor_state(raw_input="Start session")

# ✅ CORRECT - Use this instead
result = await init_anchor(
    raw_input="Start session",
    session_id="sess-001",
    auth_context={"actor_id": "user"}
)

seal_vault_commit

DEPRECATED Use: vault_seal

Legacy alias for vault_seal. Commits verdicts to the immutable VAULT999 ledger.

python

# ❌ DEPRECATED - Do not use
result = await seal_vault_commit(verdict="SEAL", evidence={...})

# ✅ CORRECT - Use this instead
result = await vault_seal(
    verdict="SEAL",
    evidence={...},
    session_id="sess-001",
    auth_context={"actor_id": "user"}
)

Internal Naming Aliases (Code-Only)

The following function aliases exist in the codebase for backward compatibility but should not be used in new implementations:

Deprecated Name	Use Instead	Notes
reason_mind_synthesis	agi_reason	AGI Mind reasoning
assess_heart_impact	asi_simulate	ASI Heart simulation
critique_thought_audit	asi_critique	ASI Critique
vector_memory_store	agi_reflect	Memory reflection
agi_asi_forge	agi_asi_forge_handler	AGI-ASI forge
apex_judge_verdict	apex_judge	APEX judgment

🔄 Migration Guide

All deprecated tools will be removed in v2027.01.01. To migrate your code:

Replace deprecated tool names with their modern equivalents
Add session_id and auth_context parameters for full governance
Update to expect RuntimeEnvelope responses instead of legacy formats
Test thoroughly before deploying to production
Update any saved tool calls in your application code