FAOS MCP Tools Reference

Complete reference for all 17 FAOS MCP tools available in Claude Desktop.

Tool Categories

Category	Tools	Purpose
Agent Invocation	1	Invoke specialist AI agents
Workflow Execution	4	Run multi-step workflows
Context & Stories	4	Access project context and stories
Activity Tracking	2	Log activities and get tasks
Metrics	3	Query business metrics
Knowledge Graph	3	Query knowledge relationships

---

Agent Invocation

faos_invoke_agent

Invoke a FAOS specialist agent to perform a task. Supports intelligent auto-routing.

Parameters:

Parameter	Type	Required	Default	Description
agent_id	string	No	"auto"	Agent ID or "auto" for intelligent routing
task	string	Yes	-	Natural language task description
context	object	No	{}	Additional context (files, state, data)
stream	boolean	No	true	Stream response progressively

Available Agents:

Agent ID	Specialty	Best For
auto	Intelligent Routing	Let FAOS pick the best agent
pm	Product Management	PRDs, requirements, stakeholder comms
dev	Development	Code review, implementation, debugging
architect	Architecture	System design, ADRs, tech decisions
analyst	Analysis	Research, market analysis, requirements
sm	Scrum Master	Sprint planning, story management

Response:

{
  "content": "Agent's response text...",
  "agent_id": "pm",
  "artifacts": [],
  "tool_calls": [],
  "session_id": "sess_abc123"
}

Examples:

Simple invocation:

"Use the FAOS dev agent to review this code for security vulnerabilities"

Auto-routing (recommended):

"Ask FAOS to help me design a REST API for user authentication"

Claude will automatically route to the architect agent.

With context:

"Use FAOS PM agent to review my PRD. Here's the draft: [paste PRD]. Focus on acceptance criteria completeness."

Iterative refinement:

1. "Ask FAOS analyst to research competitor pricing strategies"
2. "Now have the PM agent incorporate this into our pricing section"
3. "Finally, ask the architect to validate technical feasibility"

---

Workflow Execution

faos_run_workflow

Execute a multi-step FAOS workflow. Workflows automate complex processes like PRD creation or code review.

Parameters:

Parameter	Type	Required	Default	Description
workflow_id	string	Yes	-	Workflow identifier
inputs	object	No	{}	Workflow-specific inputs
wait_for_completion	boolean	No	false	Wait for completion (may timeout)

Available Workflows:

Workflow ID	Description	Duration	Key Inputs
create-prd	Create Product Requirements Document	30-60 min	product_name, target_users
create-architecture	Design system architecture	45-90 min	prd_content, constraints
create-story	Create user story from epic	10-20 min	epic_id, story_title
sprint-planning	Plan sprint from backlog	5-15 min	sprint_number, capacity
code-review	Comprehensive code review	15-30 min	file_paths, focus_areas
create-tech-spec	Technical specification	20-40 min	story_id, requirements
create-epics-and-stories	Break down PRD to epics	30-45 min	prd_content
implementation-readiness	Validate before dev	10-15 min	story_id

Response (async):

{
  "workflow_run_id": "wfrun_abc123",
  "workflow_id": "create-prd",
  "status": "running",
  "progress": 15,
  "message": "Gathering requirements..."
}

Examples:

Start a PRD workflow:

"Run the FAOS create-prd workflow for a mobile expense tracking app"

With specific inputs:

"Run FAOS code-review workflow on src/auth/*.py focusing on security and error handling"

Synchronous (short workflows):

"Run FAOS sprint-planning workflow for sprint 15 with 40 story points capacity and wait for completion"

---

faos_get_workflow_status

Check the status of a running workflow.

Parameters:

Parameter	Type	Required	Description
workflow_run_id	string	Yes	Run ID from faos_run_workflow

Response:

{
  "workflow_run_id": "wfrun_abc123",
  "workflow_id": "create-prd",
  "status": "running",
  "progress": 45,
  "current_step": "Defining user personas",
  "output": null
}

Status Values:

• pending - Queued, not yet started
• running - Currently executing
• completed - Finished successfully
• failed - Encountered error
• cancelled - Cancelled by user

Example:

"Check the status of FAOS workflow wfrun_abc123"

---

faos_cancel_workflow

Cancel a running workflow gracefully.

Parameters:

Parameter	Type	Required	Description
workflow_run_id	string	Yes	Run ID to cancel

Response:

{
  "workflow_run_id": "wfrun_abc123",
  "status": "cancelled",
  "message": "Workflow cancelled at step 3",
  "partial_output": "..."
}

Example:

"Cancel FAOS workflow wfrun_abc123"

---

faos_list_workflows

List all available workflows with their specifications.

Parameters: None

Response:

{
  "workflows": [
    {
      "workflow_id": "create-prd",
      "name": "Create PRD",
      "description": "Create comprehensive Product Requirements Document",
      "estimated_duration": "30-60 min",
      "required_inputs": ["product_name"],
      "optional_inputs": ["target_users", "competitors"]
    }
  ],
  "count": 8
}

Example:

"List all available FAOS workflows"

---

Context & Stories

faos_get_context

Get current sprint and project context.

Parameters:

Parameter	Type	Required	Default	Description
projectId	string	No	Inferred	Project ID

Response:

{
  "sprint": {
    "number": 15,
    "goal": "Complete authentication module",
    "start_date": "2026-01-20",
    "end_date": "2026-02-03"
  },
  "project": {
    "name": "FAOS Platform",
    "key": "faos"
  },
  "activeStories": [
    {"key": "55-6", "title": "Claude Desktop Integration Guide", "status": "in-progress"}
  ]
}

Example:

"Get current FAOS sprint context"

---

faos_get_story

Get full details of a specific story.

Parameters:

Parameter	Type	Required	Description
storyKey	string	Yes	Story key (e.g., "55-6")

Response:

{
  "key": "55-6",
  "title": "Claude Desktop Integration Guide",
  "status": "in-progress",
  "acceptance_criteria": [...],
  "tasks": [...],
  "dev_notes": "..."
}

Example:

"Get details for FAOS story 55-6"

---

faos_search_decisions

Search architecture decisions (ADRs).

Parameters:

Parameter	Type	Required	Description
query	string	Yes	Search query

Response:

{
  "decisions": [
    {
      "id": "ADR-001",
      "title": "Use PostgreSQL for primary database",
      "status": "accepted",
      "context": "...",
      "decision": "..."
    }
  ]
}

Example:

"Search FAOS decisions for database selection"

---

faos_get_guidelines

Get coding guidelines by category.

Parameters:

Parameter	Type	Required	Default	Description
category	string	No	"all"	Category filter

Categories: testing, api, security, database, performance, frontend, backend, deployment, all

Example:

"Get FAOS security guidelines"

---

Activity Tracking

faos_log_activity

Log developer activity for tracking and analytics.

Parameters:

Parameter	Type	Required	Description
activityType	string	Yes	Activity type (see below)
filePath	string	No	Affected file path
payload	object	No	Additional data
idempotencyKey	string	No	Prevent duplicates

Activity Types:

• artifact:created, artifact:updated
• file:create, file:update, file:delete
• tool:edit, tool:write, tool:bash
• prompt:submit
• session:start, session:stop

Example:

"Log a FAOS activity: I created the authentication module"

---

faos_get_my_tasks

Get your assigned tasks from the current sprint.

Parameters:

Parameter	Type	Required	Default	Description
status	string	No	"all"	Filter: all, in-progress, ready-for-dev, review
limit	integer	No	10	Max results (1-100)

Example:

"Show my FAOS tasks that are in-progress"

---

Metrics

faos_query_metric

Query a business metric with optional filters.

Parameters:

Parameter	Type	Required	Description
metric_name	string	Yes	Metric name
tenant_id	string	Yes	Tenant ID
dimensions	object	No	Filter dimensions
time_grain	string	No	minute, hour, day, week, month, quarter, year, all
start_date	string	No	ISO date
end_date	string	No	ISO date

Example:

"Query FAOS metric 'monthly_active_users' for January 2026"

---

faos_list_metrics

List available metrics in the catalog.

Parameters:

Parameter	Type	Required	Description
tenant_id	string	Yes	Tenant ID
category	string	No	Category filter

Example:

"List all available FAOS metrics"

---

faos_get_metric_definition

Get full metric definition including calculation logic.

Parameters:

Parameter	Type	Required	Description
metric_name	string	Yes	Metric name
tenant_id	string	Yes	Tenant ID

Example:

"Get the definition for FAOS metric 'customer_lifetime_value'"

---

Knowledge Graph

faos_query_graph

Query the knowledge graph with multi-hop traversal.

Parameters:

Parameter	Type	Required	Default	Description
start_entity	string	Yes	-	Starting entity ID/name
tenant_id	string	Yes	-	Tenant ID
max_hops	integer	No	2	Traversal depth (1-10)
relationship_types	array	No	all	Filter by relationship types
direction	string	No	"both"	in, out, both
node_types	array	No	all	Filter by node types
include_explanation	boolean	No	false	Include query explanation

Example:

"Query FAOS knowledge graph starting from 'AuthenticationService' to find its dependencies"

---

faos_nl_graph_query

Query knowledge graph using natural language.

Parameters:

Parameter	Type	Required	Description
question	string	Yes	Natural language question
tenant_id	string	Yes	Tenant ID
include_cypher	boolean	No	Include generated Cypher

Example:

"Ask FAOS knowledge graph: What components depend on the PaymentService?"

---

faos_explain_graph_query

Explain a Cypher query without executing.

Parameters:

Parameter	Type	Required	Description
cypher	string	Yes	Cypher query to explain
tenant_id	string	Yes	Tenant ID

Example:

"Explain this FAOS graph query: MATCH (n)-[:DEPENDS_ON]->(m) RETURN n, m"

---

Common Patterns

Iterative Agent Workflow

1. Start with research: "Ask FAOS analyst to research [topic]"
2. Create structure: "Have FAOS PM create an outline based on that research"
3. Add technical details: "Ask FAOS architect to add technical specifications"
4. Review: "Have FAOS dev review for implementation feasibility"

Workflow + Status Check Pattern

1. "Run FAOS create-prd workflow for [product]"
   → Returns workflow_run_id

2. [Wait a few minutes]

3. "Check status of FAOS workflow [workflow_run_id]"
   → Shows progress and current step

4. [Repeat until completed]

5. "Get the output of completed FAOS workflow [workflow_run_id]"

Context-Aware Development

1. "Get my FAOS tasks"
   → See assigned stories

2. "Get details for FAOS story [key]"
   → Understand requirements

3. "Get FAOS security guidelines"
   → Ensure compliance

4. "Ask FAOS dev agent to help implement [story requirements]"
   → Get implementation guidance

Error Handling

Error Code	Meaning	Solution
401	Authentication failed	Check/refresh token
403	Insufficient permissions	Check token scopes
404	Resource not found	Verify IDs/keys
429	Rate limit exceeded	Wait and retry
500	Server error	Contact support

See Troubleshooting for detailed error resolution.