nspec exposes 92 MCP tools. Every tool below is generated from the live @mcp.tool registry in src/nspec/interfaces/mcp/*.py, so this page stays in lockstep with the server.
Key args list each tool's parameters; a trailing * marks a required argument. Universal plumbing args (e.g. docs_root) are omitted.
Regenerate after adding tools: the parity drift test (S591) fails CI if this page and the registry diverge.
Query & Discovery
| Tool |
Purpose |
Key args |
epics |
List all epics with progress tracking. |
— |
epic_specs |
Query specs belonging to an epic, optionally filtered by status. |
epic_id*, status_filter, starting_spec_id |
show |
Show full details for a spec (FR + IMPL). |
spec_id* |
next_spec |
Find the next spec to work on based on priority and blockers. |
epic_id |
get_epic |
Get the currently active epic from the active session. |
— |
validate |
Run the 6-layer validation engine on all specs. |
— |
estimate_loe |
Estimate Level of Effort for a spec. |
spec_id* |
blocked_specs |
List specs that have blocked tasks, are paused, or in exception state. |
— |
dep_graph |
Analyze dependency graph across active specs. |
epic_id, spec_id |
preflight |
Pre-flight state snapshot for a spec before /ngo execution. |
spec_id* |
digest |
Run the nightly digest: collect activity, classify coverage, auto-file review specs. |
since, dry_run |
pr_gate |
Run the PR completeness gate. |
pr_number, base_branch |
loop_pipeline |
Return the resolved loop pipeline and agent map. |
— |
discover_providers |
Discover available provider models and configuration values. |
provider |
Spec Lifecycle
| Tool |
Purpose |
Key args |
create_spec |
Create a new FR+IMPL spec pair. |
title*, priority, epic_id, is_epic, set_default, spec_type, template |
activate |
Activate a spec by advancing its status and writing the active session. |
spec_id* |
advance |
Advance a spec to the next logical status. |
spec_id* |
complete |
Complete a spec and archive it to completed/done. |
spec_id* |
supersede |
Supersede a spec and archive it to completed/superseded. |
spec_id, superseded_by |
park |
Park a spec by setting IMPL status to Paused. |
spec_id*, reason |
park_epic |
Park all non-completed specs in an epic. |
epic_id*, reason |
exception |
Set spec to Exception state for human triage. |
spec_id, reason |
hold |
Put a spec on hold by setting IMPL to Hold state. |
spec_id, reason |
recover |
Recover a spec from Exception to Active state. |
spec_id* |
reset |
Reset a spec back to Planning state. |
spec_id* |
resume |
Resume a Paused spec to the status it held before it was parked. |
spec_id* |
start_design |
Move FR to In Design without starting IMPL. |
spec_id* |
force_archive |
Force-archive a spec that's stuck in an inconsistent state. |
spec_id, reason |
move_spec |
Reassign a spec's owning epic, or detach it from any epic. |
spec_id*, target_epic_id |
rename_spec |
Retitle a spec or epic — ID-stable heading + slug rename for both paired files. |
spec_id, new_title |
delete_spec |
Hard-delete a spec (FR+IMPL) or an epic (FR-only) — the guarded escape hatch. |
spec_id*, confirm |
unify_collisions |
Detect and resolve spec ID collisions. |
— |
init |
Initialize a new nspec project with full directory structure. |
epic_title, force |
Tasks & Acceptance Criteria
| Tool |
Purpose |
Key args |
task_complete |
Mark an IMPL task as complete. |
spec_id, task_id, marker, run_tests |
task_block |
Mark an IMPL task as blocked with a reason. |
spec_id, task_id, reason* |
task_unblock |
Remove the BLOCKED marker from an IMPL task. |
spec_id, task_id |
criteria_complete |
Mark an acceptance criterion as complete in the FR file. |
spec_id, criteria_id, marker, run_tests |
set_impl_task |
Add, edit, or remove an IMPL task line — text CRUD only (no reorder). |
spec_id, action, phase, task_id, text, file, acknowledge_completed |
set_acceptance_criteria |
Add, edit, or remove an acceptance-criterion line in an FR — text CRUD only. |
spec_id, action, section, label, text |
spec_test_files |
Manage test file entries in the ### Test Files section of an IMPL. |
spec_id*, action, files |
spec_tests |
Run only the tests relevant to a spec. |
spec_id* |
Dependencies & Priority
| Tool |
Purpose |
Key args |
add_dep |
Add a dependency to a spec. |
spec_id, dep_id |
remove_dep |
Remove a dependency from a spec. |
spec_id, dep_id |
set_priority |
Set the priority (roadmap position) of a spec or epic. |
spec_id, priority |
FR/IMPL Authoring
| Tool |
Purpose |
Key args |
refine_fr |
Check if an FR is a skeleton and generate an authoring prompt. |
spec_id* |
refine_impl |
Check if an IMPL is a skeleton and generate a refinement prompt. |
spec_id* |
write_fr_refinement |
Write agent FR authoring output to the FR file. |
spec_id, agent_output |
write_refinement |
Write agent refinement output to the IMPL file. |
spec_id, agent_output |
cheap_docs |
Generate documentation for a spec using a low-reasoning agent. |
spec_id* |
Review
| Tool |
Purpose |
Key args |
review |
Execute an atomic review cycle for a spec. |
spec_id*, base_branch, test_results, implementer |
review_spec |
Generate a review prompt for a spec to use with execute_agent(). |
spec_id*, base_branch, test_results |
write_review_verdict |
Write a review verdict to the IMPL file. |
spec_id, verdict, feedback, reviewer, implementer, review_token, verdict_token |
Sessions
| Tool |
Purpose |
Key args |
session_start |
Initialize a work session for a spec. |
spec_id* |
session_save |
Persist session state for cross-session handoff. |
spec_id*, task_id, notes, phase |
session_resume |
Load persisted session state for a spec. |
spec_id* |
session_clear |
Archive the active session and remove the active link. |
— |
session_list |
List all sessions, optionally filtered by spec ID. |
spec_id |
session_get |
Get a session by its session ID. |
session_id* |
session_delete |
Delete a session file. |
session_id* |
loop_init |
Initialize a loop session targeting a specific spec. |
spec_id* |
Checkout (lease-based reservation)
| Tool |
Purpose |
Key args |
checkout |
Reserve a spec with a TTL lease (checkout without activating). |
spec_id*, agent_id, ttl |
checkin |
Release a spec checkout reservation. |
spec_id* |
checkout_heartbeat |
Extend the lease for a checked-out spec. |
spec_id*, ttl |
checkout_status |
List all active spec checkouts with TTL remaining. |
— |
Agent Queue
| Tool |
Purpose |
Key args |
queue_init |
Initialize the agent assignment queue from the backlog. |
epic_id, max_agents, lease_ttl |
queue_claim |
Claim the next unclaimed spec from the queue. |
agent_id* |
queue_release |
Release a claimed spec back to the queue or mark it completed. |
agent_id, spec_id, reason, completed |
queue_heartbeat |
Extend the lease for an agent's current claim. |
agent_id* |
queue_status |
Get full queue status: agents, queued specs, completed specs. |
— |
Agent Swarm
| Tool |
Purpose |
Key args |
swarm_launch |
Launch a parallel Claude Code agent swarm (S253). |
epic_id*, num_agents, model |
swarm_status |
Get the current swarm status: agents, progress, and health. |
— |
swarm_teardown |
Tear down the active swarm: kill agents, clean worktrees, clear state. |
— |
Agent Execution
| Tool |
Purpose |
Key args |
execute_agent |
Execute a prompt via the configured agent for the given purpose. |
prompt, prompt_file, timeout, model, reasoning_effort, sandbox, approval_policy, flags, purpose, review_token, spec_id |
Skills
| Tool |
Purpose |
Key args |
skills_install |
Install skills to .novabuilt.dev/nspec/commands/ and sync to agents. |
force |
skills_list |
List available skills with source info. |
— |
skills_sync |
Re-sync skills from sources (update after nspec upgrade). |
force |
skills_update |
Apply skills update with user's consent choice. |
choice* |
GitHub Issues
| Tool |
Purpose |
Key args |
issue_import |
Import a GitHub issue as an nspec spec. |
repo, number, epic_id, priority, dry_run |
issue_list |
List GitHub issues from a repository. |
repo, state, label, limit |
issue_sync |
Audit GitHub issue sync for an epic — find mismatches. |
epic_id*, repo |
batch_import |
Batch-import all open non-imported GitHub issues as nspec specs. |
epic_id, repo, label |
create_issue |
Create a GitHub issue from a spec and link it. |
spec_id*, repo |
Artifacts
| Tool |
Purpose |
Key args |
artifacts_list |
List artifacts — per-spec work artifacts (when spec_id given) or nspec-managed templates. |
spec_id, artifact_type |
artifacts_sync |
Sync artifacts — recover orphaned files or sync nspec templates. |
dry_run, spec_id |
Audit & Quality
| Tool |
Purpose |
Key args |
audit_record |
Record an audit artifact (decision, inventory, or handoff). |
kind, topic, content*, related_specs |
coverage_audit |
Run full-suite coverage audit and return candidate status. |
coverage_json, registry, strict, include, exclude |
context_audit |
Analyze a CLAUDE.md file for context budget and extraction candidates. |
file, threshold |
branch_status |
List all nspec/* branches with spec ID, PR status, and ahead/behind main. |
— |
branch_cleanup |
Remove nspec/* branches whose PRs have been merged. |
dry_run |