MCP tool reference

The Troth MCP server registers 50 tools. This page is generated by building the server and reading back its registrations, so the names, descriptions and parameters here are the ones your client actually receives.

Connect the server before any of this is available. See Connect Troth to Claude.

Most tools accept an optional project parameter. Omit it to use the project selected for the session, or pass a project name to work across projects in one conversation.

Session and orientation

Call start_session first in any conversation. It composes foundations, briefing and ready tasks into one response, so the other three do not need separate calls at session open.

Tool	What it does
start_session	CALL THIS AS YOUR FIRST ACTION when the user mentions work on a project.
get_briefing	A 60-second prose briefing: where you left off, the last decision recorded, any drift, and what’s next.
next_tasks	Returns dependency-ready tasks ordered by wave, unlock power, and priority.
end_of_day_prompt	Offer at the end of a session: prose summary of what happened plus a gentle ‘any decisions to record?’ prompt.
narrated_changelog	Prose changelog organized by topic (not date).

start_session

CALL THIS AS YOUR FIRST ACTION when the user mentions work on a project. Composes foundations, briefing, and next tasks into a single round trip — no need to call get_foundations, get_briefing, and next_tasks separately at session open. Always returns foundations including the structural-map principle, even for new projects. If the project has its own constitution, it is used (source: project). If not, the built-in Troth structural-map constitution is used (source: default). Returns four fields: (1) constitution — ALWAYS present; the structural-map principle for this project; (2) foundations — full payload: design bible, tokens, asset paths; (3) briefing — last decision, current drift, what changed recently (60-second read); (4) next_tasks — top 5 dependency-ready tasks in priority order. If one section is unavailable (e.g. no foundations files, briefing service down), that section returns an error note and the other sections still populate.

Parameter	Type	Required	Description
project	string	no	Project name (optional). If omitted, uses the active session project.

get_briefing

A 60-second prose briefing: where you left off, the last decision recorded, any drift, and what’s next.

Parameter	Type	Required	Description
project	string	no	Project name (optional). If omitted, uses the active session project.

next_tasks

Returns dependency-ready tasks ordered by wave, unlock power, and priority. Use parallel to get N conflict-free tasks for simultaneous execution.

Parameter	Type	Required	Description
spec	string	no	Optional spec name to filter by
count	number	no	Max number of tasks to return (default 10)
parallel	number	no	Return N conflict-free tasks safe to run in parallel (checks file_scope overlaps)
request_id	string	no	Optional request ID or title to filter tasks to only those linked to a specific request
project	string	no	Project name (optional). If omitted, uses the active session project.

end_of_day_prompt

Offer at the end of a session: prose summary of what happened plus a gentle ‘any decisions to record?’ prompt. Not automatic — invoke when the conversation is winding down.

Parameter	Type	Required	Description
project	string	no	Project name (optional). If omitted, uses the active session project.

narrated_changelog

Prose changelog organized by topic (not date). Suitable for pasting into Slack, emails, or blog posts. Default window is 7 days.

Parameter	Type	Required	Description
since	string	no	ISO date or relative time like ‘3 days ago’ / ‘last Monday’. Default 7 days.
project	string	no	Project name (optional). If omitted, uses the active session project.

Navigation

Read the shape of a project without changing anything.

Tool	What it does
search	Full-text search across specs, tasks, findings, and decisions.
show_status	Show project-wide status overview, or drill into a specific spec for task-level progress.
show_tree	Show hierarchical project tree: specs, sub-specs, and tasks with status.

search

Full-text search across specs, tasks, findings, and decisions. Returns ranked results with matched snippets.

Parameter	Type	Required	Description
query	string	yes	Search query string
filter	"specs_only" | "tasks_only" | "findings_only" | "decisions_only"	no	Limit search to a specific type
project	string	no	Project name (optional). If omitted, uses the active session project.

show_status

Show project-wide status overview, or drill into a specific spec for task-level progress.

Parameter	Type	Required	Description
spec	string	no	Optional spec name for detail view
project	string	no	Project name (optional). If omitted, uses the active session project.

show_tree

Show hierarchical project tree: specs, sub-specs, and tasks with status. Optionally filter by spec.

Parameter	Type	Required	Description
spec	string	no	Optional spec name to show tree for (includes children)
project	string	no	Project name (optional). If omitted, uses the active session project.

Projects

A Troth account can hold many projects. With two or more, call switch_project before anything else, or pass project to an individual tool.

Tool	What it does
list_projects	List all registered projects with name, spec count, health, and active status.
switch_project	Set the active project for this session.
create_project	Create a new Troth project for a repository.
bind_local_folder	Bind a server-side project to a local folder by writing .troth/project.json and .troth/config.yaml.
rename_project	Rename a project in place.
archive_project	Archive a project, hiding it from default project lists.
unarchive_project	Restore an archived project so it appears in default project lists again.
delete_project	Permanently delete an archived project and all its data (specs, tasks, decisions, findings, requests).

list_projects

List all registered projects with name, spec count, health, and active status. Archived projects are hidden by default; pass include_archived=true to show them.

Parameter	Type	Required	Description
include_archived	boolean	no	Include archived projects (default false)

switch_project

Set the active project for this session. Persists for the conversation.

Parameter	Type	Required	Description
name	string	yes	Project name to switch to

create_project

Create a new Troth project for a repository. Auto-selects it as active.

Parameter	Type	Required	Description
name	string	yes	Project name (typically the repository or codebase name)
description	string	no	Short description of what this project is for

bind_local_folder

Bind a server-side project to a local folder by writing .troth/project.json and .troth/config.yaml. Use this after create_project so the Troth CLI can discover the project via ‘troth projects list’. Rejects if the folder is already bound to a different project.

Parameter	Type	Required	Description
project_id	string	yes	The project UUID returned by create_project
path	string	yes	Absolute path to the local repository folder to bind

rename_project

Rename a project in place. Keeps its UUID, specs, tasks, decisions, and ledger history intact — only the display name (and derived slug) change.

Parameter	Type	Required	Description
currentName	string	yes	Current project name
newName	string	yes	New project name

archive_project

Archive a project, hiding it from default project lists. All specs, tasks, decisions, and findings are preserved — use unarchive_project to restore.

Parameter	Type	Required	Description
name	string	yes	Project name to archive

unarchive_project

Restore an archived project so it appears in default project lists again. No data is modified.

Parameter	Type	Required	Description
name	string	yes	Project name to unarchive

delete_project

Permanently delete an archived project and all its data (specs, tasks, decisions, findings, requests). Two-step process: call once with just the project name to get a confirm token and data counts; call again with the same name plus the confirmToken to execute. The project must already be archived (use archive_project first). Token expires after 60 seconds — if it expires, start over.

Parameter	Type	Required	Description
name	string	yes	Project name to delete
confirmToken	string	no	Confirm token returned by the first call. Omit on first call to receive counts and a token. Provide on the second call to execute the deletion.

Specs

Specs are areas of the codebase. Call list_specs and place work inside the existing structure before creating a new one.

Tool	What it does
list_specs	List all specs in a hierarchical tree with status and task counts.
show_spec	Show a spec’s full markdown content and its tasks with status.
create_spec	Specs are areas of the codebase, not plans.
update_spec	Update a spec’s content or metadata.
archive_spec	Archive a spec, hiding it from default views.
delete_spec	Delete a spec and all its tasks permanently.
decompose	Return structured spec content (intent, criteria, constraints, bundles, existing tasks) for task decomposition.

list_specs

List all specs in a hierarchical tree with status and task counts. Archived specs hidden by default.

Parameter	Type	Required	Description
include_archived	boolean	no	Include archived specs (default false)
project	string	no	Project name (optional). If omitted, uses the active session project.

show_spec

Show a spec’s full markdown content and its tasks with status.

Parameter	Type	Required	Description
name	string	yes	Spec name
project	string	no	Project name (optional). If omitted, uses the active session project.

create_spec

Specs are areas of the codebase, not plans. Before creating, use list_specs to find where this work belongs in the existing structure. New top-level specs are rare events — only when the codebase grows a genuinely new structural area. Ask: what files does this spec own that no other spec owns? If you can’t answer that, file a task on an existing spec instead. Names must be kebab-case; use parent for sub-specs.

Parameter	Type	Required	Description
name	string	yes	Spec name
layer	"platform" | "services" | "surface"	no	Architectural layer
parent	string	no	Parent spec name for sub-specs
project	string	no	Project name (optional). If omitted, uses the active session project.

update_spec

Update a spec’s content or metadata. Content mode replaces full markdown; patch mode updates individual fields. Cannot combine both modes.

Parameter	Type	Required	Description
name	string	yes	Spec name
content	string	no	Full markdown content for the spec (content replacement mode)
layer	"platform" | "services" | "surface"	no	Architectural layer (patch mode)
parent	string | null	no	Parent spec name, or null to make top-level (patch mode)
project	string	no	Project name (optional). If omitted, uses the active session project.

archive_spec

Archive a spec, hiding it from default views. Retrievable with include_archived flag.

Parameter	Type	Required	Description
name	string	yes	Spec name to archive
project	string	no	Project name (optional). If omitted, uses the active session project.

delete_spec

Delete a spec and all its tasks permanently. Refuses if the spec has sub-specs.

Parameter	Type	Required	Description
name	string	yes	Spec name to delete
project	string	no	Project name (optional). If omitted, uses the active session project.

decompose

Return structured spec content (intent, criteria, constraints, bundles, existing tasks) for task decomposition. Create tasks from the result via create_task.

Parameter	Type	Required	Description
spec	string	yes	Spec name
project	string	no	Project name (optional). If omitted, uses the active session project.

Tasks

Tasks are units of work inside a spec.

Tool	What it does
list_tasks	List all tasks for a spec with IDs, objectives, and status.
show_task	Show a task’s full YAML: objective, file scope, verification, dependencies, and status.
create_task	Tasks live within the spec that owns the affected code.
update_task	Update task fields (status, objective, file_scope, verification, etc.).
move_task	Move a task from one spec to another, preserving all content.
delete_task	Delete a task permanently.

list_tasks

List all tasks for a spec with IDs, objectives, and status.

Parameter	Type	Required	Description
spec	string	yes	Spec name
project	string	no	Project name (optional). If omitted, uses the active session project.

show_task

Show a task’s full YAML: objective, file scope, verification, dependencies, and status. Accepts spec+task or a handle.

Parameter	Type	Required	Description
spec	string	no	Spec name (not needed if using handle)
task	string	no	Task name or handle (e.g., ‘kex-42’)
handle	string	no	Task handle (e.g., ‘kex-42’) — alternative to spec+task
project	string	no	Project name (optional). If omitted, uses the active session project.

create_task

Tasks live within the spec that owns the affected code. Before creating, use list_specs or show_spec to find where this work belongs — the spec whose file_scope covers the files you’ll touch. Do not create a new spec to house this task; find the one that already owns it. Requires objective and file_scope; include intent and behavioral verification. For tasks with migrations or deployments, include structured criteria with environment=‘production’.

Parameter	Type	Required	Description
spec	string	yes	Spec name
task	string	yes	Task name in kebab-case (e.g., ‘setup-database’)
fields	object	yes	Task fields
fields.objective	string	yes	One-sentence goal — what to do
fields.intent	string	no	Why this task exists: current state, reasoning, expected impact
fields.context	string	no	Background info and architectural notes
fields.acceptance_criteria	string | object[]	no	Testable completion conditions — either plain strings or structured SAP criteria with subject/property/expected/method. Include environment=‘production’ criteria for tasks involving migrations, API endpoints, or deployments.
fields.file_scope	string[]	no	Files this task creates or modifies (1-5 files)
fields.verification	object[]	no	Shell commands that prove completion — include at least one behavioral check
fields.guardrails	string[]	no	What NOT to do — specific boundaries to prevent side effects
fields.complexity	"simple" | "moderate" | "complex"	no	simple: mechanical, one path. moderate: some judgment, 3-5 files. complex: architectural decisions, high blast radius.
fields.dependencies	string[]	no	Task names that must complete first
project	string	no	Project name (optional). If omitted, uses the active session project.

update_task

Update task fields (status, objective, file_scope, verification, etc.). Passed/failed requires completion_notes; blocked requires blocked_reason.

Parameter	Type	Required	Description
spec	string	no	Spec name (not needed if using handle)
task	string	no	Task name or handle (e.g., ‘kex-42’)
handle	string	no	Task handle (e.g., ‘kex-42’) — alternative to spec+task
fields	object	yes	Fields to update (e.g. { status: ‘passed’ }, { status: ‘blocked’, blocked_reason: ‘waiting on X’ }, { add_guardrail: ‘Do not modify Y’ })
project	string	no	Project name (optional). If omitted, uses the active session project.

move_task

Move a task from one spec to another, preserving all content.

Parameter	Type	Required	Description
spec	string	yes	Current spec name
task	string	yes	Task name to move
target_spec	string	yes	Target spec name
project	string	no	Project name (optional). If omitted, uses the active session project.

delete_task

Delete a task permanently. Auto-removes it from other tasks’ dependency lists.

Parameter	Type	Required	Description
spec	string	yes	Spec name
task	string	yes	Task name to delete
project	string	no	Project name (optional). If omitted, uses the active session project.

Acceptance criteria

Structured criteria a machine can check, attached to a task and evaluated by troth test in the terminal.

Tool	What it does
add_criterion	Add a structured acceptance criterion to a task with auto-generated verification method.
list_criteria	List a task’s acceptance criteria with subjects, properties, and verification methods.
remove_criterion	Remove a criterion from a task (soft-delete, preserved in history).

add_criterion

Add a structured acceptance criterion to a task with auto-generated verification method.

Parameter	Type	Required	Description
task	string	yes	Task name
subject	string	yes	What to check (file path, URL, command, DB table)
property	"contains_string" | "not_contains" | "file_exists" | "http_status" | "column_exists" | "output_matches" | "count_gte" | "schema_matches"	yes	Property to evaluate
expected	string	yes	Expected value or pattern
description	string	yes	Human-readable description of the criterion
project	string	no	Project name (optional). If omitted, uses the active session project.

list_criteria

List a task’s acceptance criteria with subjects, properties, and verification methods.

Parameter	Type	Required	Description
task	string	yes	Task name
project	string	no	Project name (optional). If omitted, uses the active session project.

remove_criterion

Remove a criterion from a task (soft-delete, preserved in history).

Parameter	Type	Required	Description
criterion_id	string	yes	The criterion UUID to remove
project	string	no	Project name (optional). If omitted, uses the active session project.

Findings

Bugs and ideas captured before they become tasks.

Tool	What it does
file_bug	File a bug report.
file_idea	File a feature idea.
list_findings	List findings (bugs and ideas) with triage status and suggested spec.
confirm_finding	Confirm a finding, moving it from ‘new’ to ‘triaged’ status.
dismiss_finding	Dismiss a finding so it no longer appears in default listings.

file_bug

File a bug report. AI triage runs in the background to match it to a spec and suggest severity.

Parameter	Type	Required	Description
content	string	yes	Description of the bug
context	string	no	Additional context from the conversation
project	string	no	Project name (optional). If omitted, uses the active session project.

file_idea

File a feature idea. AI triage runs in the background to match it to a spec.

Parameter	Type	Required	Description
content	string	yes	Description of the idea
context	string	no	Additional context from the conversation
project	string	no	Project name (optional). If omitted, uses the active session project.

list_findings

List findings (bugs and ideas) with triage status and suggested spec. Defaults to non-dismissed, newest first.

Parameter	Type	Required	Description
pile_type	"bug" | "idea"	no	Filter by type
status	"new" | "triaged" | "planned" | "dismissed"	no	Filter by status
limit	number	no	Max results (default 20)
project	string	no	Project name (optional). If omitted, uses the active session project.

confirm_finding

Confirm a finding, moving it from ‘new’ to ‘triaged’ status. Use this to acknowledge a bug or idea before promoting it to a task or request.

Parameter	Type	Required	Description
finding_id	string	yes	ID of the finding to confirm
project	string	no	Project name (optional). If omitted, uses the active session project.

dismiss_finding

Dismiss a finding so it no longer appears in default listings.

Parameter	Type	Required	Description
finding_id	string	yes	ID of the finding to dismiss
project	string	no	Project name (optional). If omitted, uses the active session project.

Requests

Intent tracking that sits above specs and tasks.

Tool	What it does
create_request	Requests track intent above the spec/task layer.
list_requests	List requests with optional status and priority filters.
show_request	Show a request’s full details including linked tasks, findings, and specs.
link_to_request	Link a task, finding, or spec to a request.
resolve_request	Resolve a request with outcome and required learning.

create_request

Requests track intent above the spec/task layer. Before filing, use list_requests to search existing open requests — this work may already be tracked under an umbrella. If it is, link a task to that request instead of creating a duplicate. Use create_request for genuinely new intent: a new user report, a fresh idea, or a bug with no existing request.

Parameter	Type	Required	Description
title	string	yes	Short title summarizing the request
description	string	no	Detailed description of the request
origin	"conversation" | "bug" | "idea" | "user-report" | "internal"	no	Where this request originated (default: internal)
priority	"critical" | "high" | "normal" | "low"	no	Priority level (default: normal)
project	string	no	Project name (optional). If omitted, uses the active session project.

list_requests

List requests with optional status and priority filters. Ordered by most recent.

Parameter	Type	Required	Description
status	"open" | "in-progress" | "resolved" | "abandoned" | "deferred"	no	Filter by request status
priority	"critical" | "high" | "normal" | "low"	no	Filter by priority
project	string	no	Project name (optional). If omitted, uses the active session project.

show_request

Show a request’s full details including linked tasks, findings, and specs.

Parameter	Type	Required	Description
request_id	string	yes	Request UUID
project	string	no	Project name (optional). If omitted, uses the active session project.

link_to_request

Link a task, finding, or spec to a request. Tasks use ‘spec_name/task_name’ format.

Parameter	Type	Required	Description
request_id	string	yes	Request UUID to link to
link_type	"task" | "finding" | "spec"	yes	Type of work item to link
link_target	string	yes	Target identifier: ‘spec_name/task_name’ for tasks, finding ID for findings, spec name for specs
project	string	no	Project name (optional). If omitted, uses the active session project.

resolve_request

Resolve a request with outcome and required learning. Records resolution timestamp.

Parameter	Type	Required	Description
request_id	string	yes	Request UUID to resolve
outcome	"resolved" | "partial" | "deferred" | "wont-fix" | "cant-reproduce"	yes	Resolution outcome
learning	string	yes	What was learned from this request (required)
outcome_notes	string	no	Additional notes about the resolution
project	string	no	Project name (optional). If omitted, uses the active session project.

Decisions

The record of what was decided and why.

Tool	What it does
record_decision	Record a decision on a task with decision text and rationale.
list_decisions	List all recorded decisions across the project with rationale and context.

record_decision

Record a decision on a task with decision text and rationale. Sets task status to passed.

Parameter	Type	Required	Description
spec	string	yes	Spec name
task	string	yes	Task name
decision_text	string	yes	What was decided
rationale	string	yes	Why this decision was made (required)
project	string	no	Project name (optional). If omitted, uses the active session project.

list_decisions

List all recorded decisions across the project with rationale and context.

Parameter	Type	Required	Description
project	string	no	Project name (optional). If omitted, uses the active session project.

Foundations

Constitution, design bible, design tokens and assets. Foundations cross-cut every spec rather than belonging to one.

Tool	What it does
get_foundations	Returns workspace + project foundations (constitution, design bible, tokens, asset paths).
set_constitution	Write a constitution.md file into the foundations directory for the given scope.
set_design_bible	Write a design-bible.md file into the foundations directory for the given scope.
set_design_tokens	Write a tokens.json file into the foundations directory for the given scope.
add_design_asset	Upload a design asset (logo, swatch, reference image) into the foundations assets directory.
list_design_assets	List design assets in the foundations assets directory.

get_foundations

Returns workspace + project foundations (constitution, design bible, tokens, asset paths). Workspace and project sections are RETURNED SEPARATELY — do not expect them merged. Both sections may have null fields when files are missing; treat null as empty, not error. Asset paths list filename and absolute path only; binary contents are not returned — use native filesystem tools to read them. Call at session start to load stable project context before doing any code work.

Parameter	Type	Required	Description
project	string	no	Project name (optional). If omitted, uses the active session project.

set_constitution

Write a constitution.md file into the foundations directory for the given scope. The constitution is a foundational document describing team values, constraints, or brand positioning. Existing constitutions are NOT replaced unless overwrite=true is passed — the error message includes the existing file’s first line so you can confirm intent before replacing. Content must be non-empty. No markdown structure is enforced — constitution prose is human territory.

Parameter	Type	Required	Description
scope	"workspace" | "project"	yes	‘project’ writes to /.troth/foundations/constitution.md; ‘workspace’ writes to ~/.troth/workspaces//foundations/constitution.md
content	string	yes	Markdown body of the constitution. Must be non-empty.
overwrite	boolean	no	If true, replace an existing constitution. Default false — tool errors if file already exists.
project	string	no	Project name (optional). If omitted, uses the active session project.

set_design_bible

Write a design-bible.md file into the foundations directory for the given scope. The design bible is a foundational document describing visual language, component patterns, typography, color usage, or UX conventions. Existing design bibles are NOT replaced unless overwrite=true is passed — the error message includes the existing file’s first line so you can confirm intent before replacing. Content must be non-empty. No markdown structure is enforced — design bible prose is human territory.

Parameter	Type	Required	Description
scope	"workspace" | "project"	yes	‘project’ writes to /.troth/foundations/design-bible.md; ‘workspace’ writes to ~/.troth/workspaces//foundations/design-bible.md
content	string	yes	Markdown body of the design bible. Must be non-empty.
overwrite	boolean	no	If true, replace an existing design bible. Default false — tool errors if file already exists.
project	string	no	Project name (optional). If omitted, uses the active session project.

set_design_tokens

Write a tokens.json file into the foundations directory for the given scope. Tokens are the machine-readable design values (colors, typography, spacing, motion) that back the design bible. Tokens are validated against the tokens.schema.json schema before any filesystem write — validation failures return all errors with JSON pointer paths so you can fix specific fields. Output is pretty-printed with 2-space indent for human-diffable git history. Existing tokens.json files are NOT replaced unless overwrite=true is passed. The tokens argument may be passed as a JSON object (preferred) or a JSON string (fallback for clients that cannot pass nested structures).

Parameter	Type	Required	Description
scope	"workspace" | "project"	yes	‘project’ writes to /.troth/foundations/tokens.json; ‘workspace’ writes to ~/.troth/workspaces//foundations/tokens.json
tokens	object | string	yes	Design token values as a JSON object or JSON string. Must conform to tokens.schema.json (colors require hex, typography.faces require stack+weights, typography.scale items require size+line_height, motion items require duration_ms+easing).
overwrite	boolean	no	If true, replace an existing tokens.json. Default false — tool errors if file already exists.
project	string	no	Project name (optional). If omitted, uses the active session project.

add_design_asset

Upload a design asset (logo, swatch, reference image) into the foundations assets directory. Allowed types: SVG, PNG, JPG, WebP. Maximum size: 5 MB. Filename collisions are rejected — a rename suggestion is returned. Pass the file as base64-encoded content. In cloud mode, the tool returns filename, storage path, MIME type, size in bytes, and a 1-hour signed URL. In local mode, the tool returns the absolute path, size in bytes, and MIME type of the written file.

Parameter	Type	Required	Description
scope	"workspace" | "project"	yes	‘project’ stores under /.troth/foundations/assets/ (or Supabase Storage in cloud mode); ‘workspace’ stores under ~/.troth/workspaces//foundations/assets/
filename	string	yes	Target filename including extension (e.g., ‘logo.svg’)
content_base64	string	yes	Base64-encoded file content
overwrite	boolean	no	Replace an existing asset with the same filename (default false). When false and a collision occurs, an error is returned with a suggested alternative filename.
project	string	no	Project name (optional). If omitted, uses the active session project.

list_design_assets

List design assets in the foundations assets directory. Returns filenames, mime types, sizes, and 1-hour signed URLs that agents can fetch directly. Binary content is NOT inlined. Missing assets directory returns an empty list (not an error).

Parameter	Type	Required	Description
scope	"workspace" | "project" | "both"	no	Which scope to list (default ‘both’). In cloud mode only ‘project’ scope is supported; workspace scope returns an empty list.
project	string	no	Project name (optional). If omitted, uses the active session project.