ra-h-os/docs/4_tools-and-workflows.md

Tools & Workflows

What actions the AI can take and how workflows automate multi-step processes.

How it works: AI agents have access to tools — functions they can call to read data, create nodes, search content, and more. Workflows are pre-written instruction sets that guide the AI through complex multi-step processes like finding connections across your knowledge base.

---

Tools Overview

Tools are organized into three categories:

Category	Purpose	Examples
Core	Read-only graph operations	queryNodes, searchContentEmbeddings
Orchestration	Delegation and reasoning	executeWorkflow, think, webSearch
Execution	Write operations and extraction	createNode, updateNode, youtubeExtract

---

Core Tools (All Agents)

Read-only operations available to all agents:

queryNodes

Search nodes by title, content, or dimensions.

queryNodes({
  search?: string,      // Full-text search
  dimensions?: string[],// Filter by dimensions
  limit?: number        // Max results (default: 20)
})

getNodesById

Retrieve full node data by ID array.

getNodesById({
  ids: number[]  // Array of node IDs
})

queryEdge

Inspect existing edges between nodes.

queryEdge({
  from_node_id?: number,
  to_node_id?: number,
  limit?: number
})

searchContentEmbeddings

Semantic search across chunk embeddings.

searchContentEmbeddings({
  query: string,        // Search query
  node_id?: number,     // Scope to specific node
  limit?: number,       // Max results
  threshold?: number    // Similarity threshold (0-1)
})

queryDimensions

Query and filter dimensions.

queryDimensions({
  search?: string,      // Filter by name
  isPriority?: boolean, // Filter locked dimensions only
  limit?: number
})

getDimension

Get a single dimension by exact name.

getDimension({
  name: string  // Exact dimension name
})

---

Orchestration Tools (Orchestrators Only)

Tools for reasoning and delegation:

webSearch

External web search via Tavily.

webSearch({
  query: string,
  max_results?: number
})

think

Internal reasoning/planning (logged to metadata, not shown to user).

think({
  thought: string  // Reasoning to log
})

executeWorkflow

Delegate to wise-rah for predefined workflows.

executeWorkflow({
  workflow_key: string  // e.g., "integrate"
})

---

Execution Tools (Writers)

Write operations and content extraction:

createNode

Create a new knowledge node.

createNode({
  title: string,
  content?: string,
  description?: string,
  dimensions?: string[],
  link?: string,
  metadata?: object
})

updateNode

Append content to existing nodes. Append-only — cannot overwrite.

updateNode({
  id: number,
  content: string  // Appended to existing content
})

createEdge

Create relationship between nodes.

createEdge({
  from_node_id: number,
  to_node_id: number,
  context?: string  // Relationship description
})

updateEdge

Modify edge metadata.

updateEdge({
  id: number,
  context?: string,
  user_feedback?: number
})

Dimension Tools

createDimension({ name: string, description?: string })
updateDimension({ name: string, description?: string })
lockDimension({ name: string })    // Make priority dimension
unlockDimension({ name: string })  // Remove priority status
deleteDimension({ name: string })

Extraction Tools

youtubeExtract({ url: string })  // Extract transcript
websiteExtract({ url: string })  // Extract page content
paperExtract({ url: string })    // Extract PDF text

---

Tool Access by Agent

Agent	Core	Orchestration	Execution
ra-h / ra-h-easy	✅ All	webSearch, think, executeWorkflow	✅ All
wise-rah	✅ All	webSearch, think, delegateToMiniRAH	updateNode, createEdge
mini-rah	✅ All	webSearch, think	✅ All

---

Workflows

Workflows are multi-step instruction sets executed by wise-rah.

User-Editable Workflows

Users can create, edit, and delete workflows from Settings → Workflows tab.

Storage: ~/Library/Application Support/RA-H/workflows/

Format: JSON files with this structure:

{
  "key": "integrate",
  "displayName": "Integrate",
  "description": "Deep analysis and connection-building for focused node",
  "instructions": "You are executing the INTEGRATE workflow...",
  "enabled": true,
  "requiresFocusedNode": true
}

How Workflows Work

1. User says "run integrate workflow" (or similar)
2. Orchestrator calls executeWorkflow({ workflow_key: 'integrate' })
3. System spawns wise-rah session with workflow instructions
4. wise-rah executes steps autonomously (30-60+ seconds)
5. wise-rah returns summary to orchestrator
6. Orchestrator shows result to user

Built-in Workflows

Integrate

Key: integrate Purpose: Database-wide connection discovery Cost: ~$0.18/execution

5-Step Process:

1. Plan — Call think to outline approach
2. Ground — Extract entities (names, projects, concepts) from focused node
3. Search — Database-wide search using extracted entities
4. Contextualize — Brief relevance explanation
5. Append — Call updateNode ONCE with Integration Analysis section

Output Format:

## Integration Analysis

[2-3 sentences: what this node is, why it matters]

**Database Connections:**
- [NODE:123:"Title"] — [why relevant]
- [NODE:456:"Title"] — [why relevant]
...

**Relevance:** [1-2 sentences connecting to your context]

Creating Custom Workflows

1. Go to Settings → Workflows
2. Click "New Workflow"
3. Fill in:
   • Key — unique identifier (lowercase, no spaces)
   • Display Name — shown in UI
   • Description — what it does
   • Instructions — the prompt for wise-rah
   • Requires Focused Node — whether a node must be selected
4. Save

Workflow Instructions Tips

• Be explicit about steps and expected output
• Reference tools by name (wise-rah has: queryNodes, searchContentEmbeddings, updateNode, createEdge, webSearch, think)
• Specify output format precisely
• Include guardrails ("call updateNode exactly once")

---

Tool Registry

Location: src/tools/infrastructure/registry.ts

Structure:

TOOL_SETS = {
  core: { queryNodes, getNodesById, queryEdge, queryDimensions, getDimension, searchContentEmbeddings },
  orchestration: { webSearch, think, delegateToMiniRAH, executeWorkflow, ... },
  execution: { createNode, updateNode, createEdge, updateEdge, youtubeExtract, websiteExtract, paperExtract, ... }
}

---

Key Design Decisions

Append-Only Updates

updateNode is append-only — it cannot overwrite existing content. This prevents AI from accidentally destroying knowledge. The tool-level enforcement means workflows can't bypass this restriction.

No Workflow Delegation Loops

wise-rah cannot call executeWorkflow or delegate to other wise-rah instances. This prevents infinite loops and keeps execution bounded.

Isolated Execution

Workers (wise-rah, mini-rah) execute in isolated sessions. They return structured summaries only — they don't pollute orchestrator context with execution details.