Tools & resources

This is the full reference for the hosted server at https://www.intentdocs.com/api/mcp, then the local server started by npx intentdocs mcp. For how the pieces fit together, read the MCP overview first.

The hosted server registers 42 tools, one resource and two prompts. The published manifest at GET /api/mcp/manifest lists the same 42 tools with the same parameter names.

Before you read the tables

project_id. Every hosted tool except list_projects and create_project takes project_id: a project UUID, required. The tables below leave it out. Get it from list_projects, or from create_project when the project is new.

Story references. Tool tables say which forms story_id accepts:

• Key or UUID: a key like PB-42, or a full UUID.
• Key, UUID or prefix: also a UUID prefix, such as the first 8 characters.

update_stories takes full UUIDs in stories[].id. get_story also accepts a build-sequence reference like #5.

Access. Reads need any role on the project. Writes need editor or owner. add_note needs comment access. A project you can't reach is refused as "Project not found or access denied". A refused write names the capability it needs.

Common refusals. "No story map found for this project" when the project has no map. "No story found matching ..." when a story reference names nothing. update_stories, create_stories and set_vision refuse with "Trial expired. Upgrade at https://intentdocs.com/pricing" when the map owner's trial has ended.

Criterion input. create_stories, add_criteria, replace_criteria and preview_criteria_replacement take criteria as plain strings, or objects:

Field	Type	Meaning
text	string, required	The criterion, e.g. "Given X, when Y, then Z".
priority	must, should or could	Defaults to should.
given, when, then	string	The criterion split into parts.
verification	object	method is executable, agent_self_check, visual_render or founder_confirm. Optional command, check_prompt, expected.

A criterion read back from get_story can be passed straight back. Every bad field in a batch is reported at once, naming the field and what it accepts, and nothing is written.

Title and effect. This table is generated from the same hint table the server and GET /api/mcp/manifest use. Title is the human name a directory shows next to the tool. Effect is Read when the tool changes nothing, and Write when it changes the founder's project.

Tool	Title	Effect
list_projects	List projects	Read
get_context	Get project context	Read
get_session_context	Get session context	Read
list_stories	List stories	Read
get_story	Get story details	Read
get_status	Get project status	Read
get_build_order	Get build order	Read
get_vision	Get vision	Read
get_constitution	Get vision	Read
find_orphaned_releases	Find orphaned releases	Read
check_release_readiness	Check release readiness	Read
preview_criteria_replacement	Preview criteria replacement	Read
propose_drift_fix	Propose drift fix	Read
analyze_complexity	Analyze story complexity	Read
research	Research a question	Read
import_prd	Import PRD document	Read
get_run	Read a build run	Read
get_founder_todo	What's waiting on me	Read
create_project	Create a project	Write
archive_project	Archive a project	Write
restore_project	Restore an archived project	Write
create_stories	Create stories	Write
add_criteria	Add acceptance criteria	Write
start_story	Start a story	Write
next_in_run	Next story in a build run	Write
uncancel_story	Restore a cancelled story	Write
raise_blocker	Raise a blocker	Write
needs_founder	Hand a step to the founder	Write
add_note	Add implementation note	Write
log_decision	Log a decision	Write
complete_story	Complete a story	Write
link_pr	Link pull request	Write
get_design	Fetch a design reference	Write
update_stories	Update stories	Write
rename_release	Rename a release	Write
replace_criteria	Replace all criteria	Write
update_criterion	Edit one criterion	Write
set_vision	Set vision answers	Write
set_constitution	Set vision answers	Write
amend_decision	Amend a decision	Write
retract_decision	Retract a decision	Write
cancel_story	Cancel a story	Write
save_plan	Save implementation plan	Write
report_criteria	Report criteria results	Write
save_tests	Save tests	Write
save_design	Attach a design reference	Write

Kind. The sections below split writes into adds and overwrites. Clients use the hints to decide what to confirm with you.

Projects and context

Tool	Purpose	Kind
list_projects	List every project you can reach, with vision status.	Read
create_project	Create a project in the founder's personal workspace from an agreed name and a one-line idea.	Adds
get_session_context	One compact summary to start a session.	Read
get_context	The full spec as INTENT.md.	Read
get_status	Progress, cancelled stories, drift, CI regressions, sync state.	Read

list_projects

No parameters. Returns a JSON array. Each project has id, name, description, created_at, has_synced, vision_status, vision_progress, and the same values as constitution_status and constitution_progress. A second text block names the workspace the token reads from. With no projects, the array is [].

create_project

Param	Type	Required	Meaning
name	string	Yes	The project name the founder agreed to.
idea	string	Yes	A one-line description of the idea.

Creates the project in the founder's personal workspace and returns project_id plus a link to open it. The same name and idea again within a few minutes returns that project instead of creating a second one. When the plan has no free project slot, nothing is created and the response says why, linking only to the plans page. It is a write that creates something, so hosts ask before running it. The project's activity records that it was created from a chat assistant and names the client.

get_session_context

No parameters beyond project_id. Returns workspace, project, constitution (status, progress, and summary or unanswered), stories, sync and blockers.

stories has counts by status, total, cancelled, map_id, and either current (the story in progress, with its criteria) or next (the highest-priority todo). It also lists spec_changed_since_built when built stories' specs have moved. Cancelled stories are left out of the counts.

get_context

Param	Type	Required	Meaning
agent_type	claude_code, cursor, copilot or windsurf	No	Which agent is calling.

Returns the project's INTENT.md as Markdown: brief, personas, activities, release labels, stories with their criteria and design references, and going-live answers. Parked backlog ideas are left out.

get_status

No parameters beyond project_id. Returns a text summary: complete count and percentage, approved, dev complete (done), in progress and todo. It then lists the vision state, cancelled stories ("stop all work on these"), stories whose spec changed since they were built, done or approved stories whose criteria now fail in CI, and the sync state: last activity, first sync, and stories with no reported evidence. Counts leave out cancelled stories and parked ideas. Renders a progress card.

Vision

Tool	Purpose	Kind
get_vision	Read the five vision questions and answers.	Read
set_vision	Save answers, in full or in part.	Overwrites

get_constitution is an alias of get_vision, and set_constitution of set_vision. Same schema, same result.

get_vision

No parameters beyond project_id. Returns status (missing, draft or complete), progress, unanswered, and questions. Each question has key, heading, hint, text and answered_at. A complete vision also has a short summary.

set_vision

Param	Type	Required	Meaning
answers	object	One of these two	Keys users, problem, switch, first, proof, each a non-empty string. Keys you leave out are untouched.
report	string	One of these two	A brownfield report to derive answers from. Only users can be derived from a codebase.
confirm	boolean	No	Required when a report-derived answer would replace an answered key.

With both, answers wins for the keys it names. Returns status, progress, unanswered, next_step and questions, plus missing_constitution_keys for a report.

Refused with neither parameter, or with error: "invalid_report" and the problems. A report that would overwrite an answer returns requires_confirmation: true and would_overwrite, and writes nothing until you call again with confirm: true.

Stories

Tool	Purpose	Kind
list_stories	List stories with filters.	Read
get_story	Everything about one story.	Read
create_stories	Add stories, by hand or from a brownfield report.	Adds
update_stories	Change story fields, in a batch.	Overwrites
cancel_story	Stop work on a story, reversibly.	Overwrites
uncancel_story	Restore a cancelled story.	Adds
import_prd	Parse a PRD into a story structure. Saves nothing.	Read

list_stories

Param	Type	Required	Meaning
status	todo, ready_for_dev, in_progress, needs_rework, done or approved	No	Filter by status.
activity	string	No	Filter by activity name, ignoring case.
release	number	No	Filter by release number.
limit	number	No	Maximum stories. Defaults to 200.
fields	array of criteria, notes, user_story, depends_on, build_sequence	No	Extra detail per story.

Returns map, stories and summary. Each story has id, key, title, status, activity, release, priority, effort, criteria_count, passing_count and version, plus cancelled_at and cancellation_reason when cancelled. When the limit cuts the list, the result has truncated, showing and total_matching. Parked ideas are left out.

get_story

Param	Type	Required	Meaning
story_id	string	Yes	Key, UUID, prefix, or build-sequence reference like #5.

Returns the story with:

• key, suggested_branch, title, status, activity, user_story, priority, effort, release, build_sequence, depends_on, version
• claim: who is building it, the client, claimed_at, last_seen_at, and state (held or stalled)
• acceptance_criteria: each with id, text, priority, given/when/then, verification, last_result, test_count, and ci_regressed when CI now fails it
• tests, and test_coverage with untested_criteria and unlinked_tests
• plan (the structured plan, its version and review state), plan_feedback, plan_warnings, and the older implementation_plan when there is one
• notes, review_notes, implementation_summary, implemented_files, implemented_at
• spec_changed_since_built, and tests_predate_code when results are older than the latest code change in the linked PR
• design_refs: each with id, kind, url, selector, match_instruction, drifted
• record (who marked it ready, built it and approved it) and history (every status change, by whom and from where)

Renders a story card.

create_stories

Param	Type	Required	Meaning
stories	array	One of stories or report	Stories to create.
stories[].title	string	Yes	Story title.
stories[].activity	string	No	Activity name. Created if new.
stories[].as_a, i_want, so_that	string	No	The user story.
stories[].priority	must, should or could	No	Defaults to should.
stories[].effort	XS, S, M, L or XL	No	Defaults to M.
stories[].release_order	number	No	Defaults to 1. See Releases.
stories[].acceptance_criteria	array	No	See criterion input above.
report	string	One of stories or report	A brownfield report. Each bullet under "Existing features" becomes a story, under the activity "Existing functionality (from brownfield report)".
confirm	boolean	No	Required when report targets a map that already has stories.
force	boolean	No	Skip the vision gate. Not recommended.

New stories start as todo. A title that matches a live story on the map, ignoring case, is skipped rather than duplicated.

Returns created, and stories with each new story's id, title and criteria ids. Also skipped_duplicates when titles were skipped, and missing_constitution_keys and missing_sections for a report.

Refused without a complete vision (error: "constitution_required"), for bad criteria (nothing is created), or for a release out of sequence. A report on a non-empty map without confirm returns requires_confirmation: true with a stories_preview, and writes nothing.

update_stories

Param	Type	Required	Meaning
stories	array	Yes	One entry per story.
stories[].id	string (UUID)	Yes	The story.
stories[].expected_version	number	No	Refuse if the story changed since this version.
stories[].status	todo, in_progress, needs_rework or done	No	ready_for_dev and approved are refused: a person sets them in the app.
stories[].title, priority, effort		No	As in create_stories.
stories[].release	number	No	Move to this release. The next sequential number creates it.
stories[].activity	string	No	Move to this activity. It must exist.
stories[].sort_order	number	No	Position in its activity lane, from 0.
stories[].build_sequence	number or null	No	Place in the build order, from 1. null clears it.
stories[].dependencies	array of UUIDs	No	Replaces the story's dependencies.
stories[].notes	string	No	Replaces the notes. To append, use add_note.
stories[].implementation_summary, implemented_files		No	What was built.
stories[].as_a, i_want, so_that	string	No	The user story.

Returns updated, the applied stories, dependencies_updated, and readyReleases with a release_note when a release can now be closed.

Refused for human-only statuses, an unknown activity (the valid names are listed), a release out of sequence, or a dependency outside the project. With expected_version, every row is checked before any is written. One stale row refuses the batch with VERSION_CONFLICT and stale_stories.

Setting status: "done" here skips the must-criteria gate and doesn't release the story's claim. To finish a story you built, use complete_story.

cancel_story

Param	Type	Required	Meaning
story_id	string	Yes	Key, UUID or prefix.
reason	string	No	Shown wherever the story appears.

Drops the story from progress counts and "what's next" answers. Its status stays as it was, and nothing is deleted. Returns cancelled: true, status_preserved, cancellation_reason and effect. Refused when the story is already cancelled.

start_story and complete_story refuse cancelled stories, with the reason.

uncancel_story

Param	Type	Required	Meaning
story_id	string	Yes	Key, UUID or prefix.

Restores the story at the status it was cancelled at, never reset to todo. Refused when the story isn't cancelled.

import_prd

Param	Type	Required	Meaning
prd	string	Yes	The PRD or spec text.
format	PRD, Markdown or text	No	Defaults to PRD.
force	boolean	No	Skip the vision gate. Not recommended.

Parses the text with AI. Returns hierarchy (activities, their steps and stories with acceptance criteria), a summary of counts, and existingActivities. It doesn't write stories to the map. Pass the stories you want to create_stories.

Refused without a complete vision. A failed parse returns "PRD import failed" with the HTTP status.

Building a story

Tool	Purpose	Kind
start_story	Claim a story and get everything needed to build it.	Adds
save_plan	Save the next version of a story's plan.	Overwrites
save_tests	Save tests and link them to criteria.	Overwrites
report_criteria	Record pass, fail or blocked per criterion.	Overwrites
raise_blocker	Record a blocker and the decision needed.	Adds
add_note	Append an implementation note.	Adds
complete_story	Mark a story done, with a summary and PR.	Adds
link_pr	Link a pull request to a story.	Adds

start_story

Param	Type	Required	Meaning
story_id	string	Yes	Key, UUID or prefix.
release_current	boolean	No	This session already holds another story: put it back and start this one.

Sets the story to in_progress and claims it for this session. A story with no build sequence is added to the end of the build order.

Returns story_id, title, status, priority, effort, release, build_sequence, version, user_story, notes, acceptance_criteria, plan and plan_feedback, design_refs, affected_built_stories, warnings and note. You don't need get_story as well. Renders a story card.

warnings can say: the story was already in progress; it was taken over from a quiet session; another session's plan touches the same files; other stories are in progress; criteria have no linked test yet; the story has no criteria or no plan; it is outside the current release; or the plan touches files that built stories own, which you should re-verify before completing.

Refused when the story is cancelled, when the project's build gate isn't met, when this session already holds another story (unless release_current: true), or when another live session holds it. See One story per session.

save_plan

Param	Type	Required	Meaning
story_id	string	Yes	Key, UUID or prefix.
steps	array, at least one	Yes	The whole new version, in order.
steps[].text	string	Yes	The step.
steps[].id	string	No	The step's id from the current plan (s1, s2, ...) when this step continues one.
steps[].files	array of strings	No	Files this step creates or changes.
questions	array of text and optional options	No	Things a person needs to decide before building.
risk	string	No	One line on what could go wrong. Shown to the reviewer first.
responses	array of feedback_id and reply	When changes were requested	Your answer to every point in plan_feedback.
expected_version	number	No, but recommended	Refuse if the story changed since you read it.

Returns story_id, the saved plan, review: "awaiting", how many feedback points were answered, and warnings.

Refused with FEEDBACK_UNANSWERED and the open plan_feedback when a requested change has no response, or VERSION_CONFLICT. Steps a person edited keep their words: pass their id and text unchanged. A save that rewords or drops one is saved, recorded as a conflict for the reviewer, and warned about.

save_tests

Param	Type	Required	Meaning
story_id	string	Yes	Key, UUID or prefix.
tests	array, at least one	Yes	Tests to add or link.
tests[].id	string	No	An existing test's id, to set its links. Omit to add a new test.
tests[].title	string	Unless id is given	The new test's title.
tests[].steps, expected_result	string	No	How to run it and what passing looks like.
tests[].test_type	functional, edge_case, integration or error_handling	No	Defaults to functional.
tests[].criterion_ids	array of strings	No	Full ids of the criteria this test proves. Prefixes aren't accepted here. One test can prove several.
tests[].file	string	No	Test file path as JUnit reports it, e.g. src/lib/__tests__/foo.test.ts.
tests[].full_name	string	No	Full test name as JUnit reports it, e.g. MyLib > when X > does Y. Set with file to match CI results.

Returns added, linked, tests, untested_criteria and unlinked_tests. A criterion id that isn't a live criterion on the story is refused, with the valid ids listed, and nothing is saved. So is an id that names no test on the story.

report_criteria

Param	Type	Required	Meaning
story_id	string	Yes	Key or UUID.
results	array	Yes	One entry per criterion.
results[].criterion_id	string	Yes	Full id, or a prefix of at least 4 characters that names one criterion.
results[].status	pass, fail or blocked	Yes	The result.
results[].detail	string	No	What you observed.
results[].caveat	string	No	Anything a person should read before accepting this result. A result with a caveat is never bulk-approved.
results[].tests	array of file, full_name, optional title	No	Tests that prove this criterion. Saved as the story's tests and linked.
expected_version	number	No	Refuse if the story changed since this version.

Each result is stored as the criterion's latest, with its attempt number and time. A story still todo moves to in_progress and is claimed for this session. Reporting also clears the story's "code changed" flag.

Returns updated, passed, failed, started when the story was started, tests_saved when tests were named, and the full criteria list.

If any criterion_id names no criterion, names more than one, or appears twice, the whole report is refused, nothing is saved, and the valid ids are listed. Also refused with VERSION_CONFLICT.

raise_blocker

Param	Type	Required	Meaning
story_id	string	Yes	Key, UUID or prefix.
summary	string	Yes	Short summary.
attempting	string	Yes	What you were trying to do.
failing	string	Yes	What's failing and why.
decision_needed	string	Yes	The single decision the owner needs to make.
criterion_id	string	No	The blocked criterion.
attempts	number	No	How many fix attempts were made. Defaults to 1.

Records the blocker on the story and in the project's activity. Returns the summary and the decision needed. Stop work on the story after calling it.

add_note

Param	Type	Required	Meaning
story_id	string	Yes	Key, UUID or prefix.
note	string	Yes	The note.

Appends to the story's notes after a blank line. Needs comment access, not edit access.

complete_story

Param	Type	Required	Meaning
story_id	string	Yes	Key, UUID or prefix.
summary	string	Yes	What you built, key decisions, anything the owner should know.
implemented_files	array of strings	No	Files created or changed.
pr_url	string (URL)	No	The pull request to link and stamp.
force	boolean	No	Mark done even with failing must criteria. Use sparingly.

Sets the story to done, saves the summary and files, releases the claim and links the PR. When GitHub is connected, the PR body is stamped with the IntentDocs footer. Otherwise the response gives you the footer line to add.

The response is text. It names must criteria with no linked test, files that overlap built stories or another session's planned work, and, when the GitHub App is installed, files that differ between implemented_files and the PR. It ends with the next story in the release by build sequence, and the top of the whole build order when that is a different story. Renders a story card.

Without force, it refuses while any must criterion is failing or unreported, listing each with its state. It can also refuse when implemented_files overlaps built stories and the project's PR check is set to require action. Fix and report, or pass force: true. Refused for a cancelled story.

link_pr

Param	Type	Required	Meaning
story_id	string	Yes	Key, UUID or prefix.
pr_url	string (URL)	Yes	e.g. https://github.com/org/repo/pull/123

Saves the link, so the PR number shows on the story card, then stamps the PR body as complete_story does. The link is saved even when stamping fails.

Criteria

Tool	Purpose	Kind
add_criteria	Append criteria to a story.	Adds
update_criterion	Change one criterion's text or priority.	Overwrites
preview_criteria_replacement	Show what a replacement would change.	Read
replace_criteria	Replace all of a story's criteria.	Overwrites

report_criteria is under Building a story.

add_criteria

Param	Type	Required	Meaning
story_id	string	Yes	Key or UUID.
criteria	array	Yes	Criteria to append.

Existing criteria are kept. Returns added, total, and the new criteria with their ids. Bad criteria are refused, and nothing is added.

update_criterion

Param	Type	Required	Meaning
story_id	string	Yes	Key or UUID.
criterion_id	string	Yes	The full criterion id.
text	string	One of text or priority	New wording.
priority	must or should	One of text or priority	New priority.
expected_version	number	No	Refuse if the story changed since this version.

Every other criterion, and this criterion's id and results, stay as they are. Returns updated_criterion and other_criteria_untouched. Refused with nothing to change, an unknown id (the valid ids are listed), or VERSION_CONFLICT.

preview_criteria_replacement

Param	Type	Required	Meaning
story_id	string	Yes	Key or UUID.
criteria	array	Yes	The proposed full set.

Writes nothing. Returns would_remove, would_add, removing (with has_results and last_status for each), adding, and an evidence_warning when criteria with reported results would be discarded.

replace_criteria

Param	Type	Required	Meaning
story_id	string	Yes	Key or UUID.
criteria	array	Yes	The full new set.
expected_version	number	No	Refuse if the story changed since this version.
dry_run	boolean	No	Deprecated. Use preview_criteria_replacement.

Deletes every criterion and inserts the new set. On a done or approved story, a new criterion worded the same as an old one keeps the old id and result. Returns replaced and the new criteria with their ids. Refused for bad criteria or VERSION_CONFLICT.

Build order and runs

Tool	Purpose	Kind
get_build_order	The order stories are built in.	Read
get_run	A build run and all its stories.	Read
get_founder_todo	Everything waiting on the founder, across every project.	Read
next_in_run	Start the next story in an approved run.	Adds

get_build_order

No parameters beyond project_id. Returns order, each story with id, title, activity, effort, priority, status, build_sequence, depends_on and reason. Also generated_at. Stories with no build order yet are listed under unsequenced (each with unsequenced: true, its release and story_url), with a note saying how many.

The order lists stories with a build sequence, and finished stories; agents don't build an unsequenced story until it's sequenced. Sequence the rest on the Plan view. If the project offers current-release stories first, those come first, in their existing order. Renders a card with a reorderable build order.

get_run

Param	Type	Required	Meaning
run	string	Yes	The run's key, like R-7, or its id.

Returns run (key, id, title, status, concurrency, on_failure), progress, and stories in build order. Each story has its status, claim, pull request, has_plan, plan_steps and acceptance_criteria with each result. next says what to do: call next_in_run, wait for approval, or stop. Refused when no run matches.

get_founder_todo

Param	Type	Required	Meaning
project_id	string (uuid)	No	Only this project's items. Omit it for every project.

Returns what waits on the founder, most unblocking first: steps an agent handed them (needs_founder), blockers, plans awaiting approval (or approved before the spec changed), and built stories awaiting acceptance. An item that unblocks more unbuilt stories comes first, then items in an approved run. Each item has a url to the page where it's cleared, plus kind, story_key, action, detail, unblocks and run. get_status ends with the same list for its project, and the app's To do page and the daily email carry it too. On both addresses.

next_in_run

Param	Type	Required	Meaning
run	string	Yes	The run's key, like R-7, or its id.

When there is a story to build, starts it and returns what start_story returns, plus run with key, position and of. Call it again after each complete_story.

Otherwise returns run, state and message, and you stop. state is draft, paused, cancelled, stopped, complete, full or waiting. waiting includes waiting_on, the stories the rest depend on. When a run completes and the next phase is lined up as a draft for a person to approve, next_run names it. Don't start it until next_in_run hands it out.

Releases

Tool	Purpose	Kind
check_release_readiness	Pre-flight check before building a release.	Read
rename_release	Rename a release.	Overwrites
find_orphaned_releases	Find releases stories use but the canvas can't show.	Read

Releases are created by placing stories in them. Pass the next sequential number as release in update_stories or release_order in create_stories, and the release is created, as the canvas's "Add release" does. A bigger jump is refused, naming the next available number. Release 1000 is Go live, the release every project ends with.

A release number stories use with no label is an orphan, and the canvas doesn't show it. Placing a story in an orphan creates its label.

check_release_readiness

Param	Type	Required	Meaning
release_order	number	No	The release to check. Omit it to check the current release: the one the team made current, else the first that isn't closed.

Show the report to the person and ask before building.

Returns release, release_order, auto_selected, selection_reason, counts (total, done, in_progress, to_build), gaps, verification_gaps, blocking, advisory, ready and a Markdown report. Renders a progress card.

• Gaps block the verdict: a story to build with no criteria, or no must criteria.
• Verification gaps also block: a finished story with no passing result, or with passing results reported more than an hour before it was implemented.
• Advice doesn't block: stories with no plan, under advisory.missing_plans.
• Acceptance says how approved stories were accepted: reviewed by someone else, self-accepted, carried end to end by one person, or approved before the record began. A viewer's agent doesn't get it.

An unknown release is refused, listing the valid releases.

rename_release

Param	Type	Required	Meaning
release_order	number	Yes	The release to rename.
label	string	Yes	The new name.

Returns release_order, previous_label and label. Refused when the release doesn't exist yet. Create it first by placing a story in it.

find_orphaned_releases

No parameters beyond project_id. Returns orphaned_releases, and orphans with each release number, its story_count and stories. When there are orphans, fix says how to heal one: call update_stories on one of its stories with release set to that number.

Decisions

Tool	Purpose	Kind
log_decision	Record a decision.	Adds
amend_decision	Correct a decision.	Overwrites
retract_decision	Withdraw a decision, keeping the record.	Overwrites

log_decision

Param	Type	Required	Meaning
title	string	Yes	Short title.
description	string	Yes	What was decided and why.
category	architecture, product, technical or trade-off	No	Defaults to technical.
story_id	string	No	A story to link it to.

Records the decision and an activity entry. Returns a confirmation with the title.

amend_decision

Param	Type	Required	Meaning
decision_id	string	Yes	Full UUID or prefix.
title, description	string	At least one field	The new text.
category	as in log_decision	At least one field	The new category.

Refused with nothing to change, an unknown id, or a retracted decision.

retract_decision

Param	Type	Required	Meaning
decision_id	string	Yes	Full UUID or prefix.
reason	string	No	Why.

Marks the decision retracted with a time and reason. Nothing is deleted. Refused when already retracted.

Design

Tool	Purpose	Kind
save_design	Attach a design reference to a story.	Overwrites
get_design	Fetch a Figma or Claude design for a story.	Adds

save_design

Param	Type	Required	Meaning
story_id	string	Yes	Key, UUID or prefix.
url	string	Yes	A Figma frame, a claude.ai design, an image, a Storybook story, or a repo-relative path.
kind	figma, claude-design, image-url, repo-path, storybook or other	No	Inferred from the URL when left out.
selector	string	No	Frame or node id, Storybook path. Taken from the URL where possible.

The reference shows under Spec › Design, grouped by the story's activity. Attach the same URL to every story a screen covers. Existing references stay. Returns ref and design_refs_count, or already_attached: true with the existing reference.

get_design

Param	Type	Required	Meaning
story_id	string	Yes	Key, UUID or prefix.
ref_id	string	No	Which reference, from get_story's design_refs. Omit when the story has one Figma or Claude design reference.

Fetches the design so the agent can see it without its own credentials: the HTML of a Claude design, or Figma's node or file JSON. Returns ref_id, kind, url, content_type, content (the first 50,000 characters), fetched_at, content_hash and drifted. drifted: true means the design changed since an earlier fetch. Only the hash and time are stored.

Other kinds have nothing to fetch: open their URL. Figma needs a token configured on the IntentDocs server. Without one, the result says Figma isn't configured. A failed fetch returns error: "FETCH_FAILED".

Drift and analysis

Tool	Purpose	Kind
propose_drift_fix	Propose how to settle a story whose spec drifted after it was built.	Read
analyze_complexity	Score stories' complexity with AI.	Read
research	Research a question with the project as context.	Read

propose_drift_fix

Param	Type	Required	Meaning
story_id	string	Yes	Key, UUID or prefix. The story must be drifted (code_changed or regressed).

Reads the PR diff and the spec, then proposes either spec changes that lock in what was built, or a rework note for the code. Nothing is written. A person accepts the proposal or sends the story back. Returns text with the drift, the verdict (update_spec or rework), the reasoning, and the spec changes or rework instruction. A story with no drift says so.

analyze_complexity

Param	Type	Required	Meaning
story_ids	array of strings	No	Stories to analyze. Defaults to every story not done.

Returns, per story, a complexity score from 1 to 10, the reasoning, risks and a suggested effort. Nothing is saved.

research

Param	Type	Required	Meaning
query	string	Yes	What to research.

Returns findings, recommendations, risks and next steps as text. Nothing is saved.

Resources and prompts

Card resource

The hosted server registers one resource, ui://intentdocs/card.html. Clients that support MCP Apps, such as Claude.ai and Claude Desktop, render it as an interactive card beside these tools' results:

• Story card: get_story, start_story, complete_story
• Progress card: get_status, check_release_readiness
• Build order card, which can reorder stories: get_build_order

A card-bearing tool's structuredContent carries everything its text does, plus a card object. Some clients show the agent structuredContent instead of the text, so nothing is lost either way. Cards name stories by their keys.

Prompts

spec-my-idea takes no arguments. It starts the flow described on Spec my idea. The prompt, the server instructions and that page are one text.

intentdocs-workflow takes no arguments. It returns a guide to the workflow: orient, check release readiness, pick a story, start it, build, save tests, report criteria, raise blockers, complete, repeat. Its examples use the same tools and parameters as this page.

Local server

The local server, started by npx intentdocs mcp, is a separate, smaller server. Its tools act on the one project linked in .intent/config.json, so none of them take project_id. It authenticates with the login saved by npx intentdocs login. story_id accepts a story key like PB-42, a full UUID or a UUID prefix.

--mode picks the tools. Each mode includes the ones before it. The default is all. A tool outside the current mode is refused with the mode it needs.

Core (7 tools)

Tool	Parameters	What it does
list_stories	filter (optional): todo, in_progress, done, or a search term	Stories with status, priority, effort and criteria, and a summary.
mark_in_progress	story_id	Mark a story in progress.
report_criteria	story_id, results of criterion_id, status (pass, fail or blocked), optional detail and attempt	Report criteria results.
raise_blocker	story_id, summary, attempting, failing, decision_needed, optional criterion_id and attempts	Record a blocker. Stop work after, and don't call mark_done.
mark_done	story_id, optional force	Mark done. Returns the blocking list instead while any must criterion is failing or unreported, unless force: true.
get_status	none	Done, in progress and todo counts.
add_note	story_id, note	Add an implementation note.

Standard (adds 5)

Tool	Parameters	What it does
create_story	title, optional activity, priority (must, should, could), effort (S, M, L, XL)	Create one story.
get_context	none	The project's INTENT.md.
log_decision	title, description, optional category, story_id	Record a decision.
amend_decision	decision_id, optional title, description, category	Correct a decision.
retract_decision	decision_id, optional reason	Withdraw a decision.

All (adds 3)

Tool	Parameters	What it does
analyze_complexity	optional story_ids	AI complexity scores.
research	query	AI research with project context.
import_prd	prd, optional format (PRD, Markdown, text)	Parse a PRD into stories.

Resources

Always available, whatever the mode:

Resource	URI	Type
Story Map	intentdocs://project/storymap	text/markdown
Stories	intentdocs://project/stories	application/json
Project Status	intentdocs://project/status	application/json
Decisions	intentdocs://project/decisions	application/json
Data Model	intentdocs://project/data-model	application/json
Build Order	intentdocs://project/build-order	application/json

Cancelled stories

If a story has been cancelled, the local server refuses every tool call that names it, except list_stories and get_status. The response starts "Development of ... was cancelled" and tells the agent to stop all work on it. Treat it as a hard stop, not an error to retry.

What the local server doesn't have

There are no claims, build runs, plans, tests, design tools or PR linking. mark_in_progress and mark_done are the local equivalents of start_story and complete_story, without the claim, the summary or the next-story handout.