Fagan

Overview Schema Source Related Servers Discussions Admin

mark_story_done

Marks a story as finished after its PR merges, updating the ticket and plan status, and triggering plan completion when it's the final story.

Instructions

Mark a story finished: sets its ticket (Plane, when enabled) to Done, sets manifest["stories"][story_key]["status"] to "done", and clears any stale parked_reason. If this was the plan's last remaining story, fires the plan-completion notification.

plan_name: the plan's name, as returned by list_plans or passed to save_plan/ingest_plan. story_key: the story's key within that plan's manifest, as returned by list_ready_stories, check_story_status, or dispatch_story.

Call this only after the story's PR has actually been reviewed and merged — approve_merge already calls this internally as its last step, so you normally only need to call mark_story_done directly for a merge that happened outside the pipeline (e.g. a manual gh pr merge you've already confirmed passed CI). It does not merge or verify anything itself; it only records that the work is done. If another dispatch/ingest/interrupt holds the plan's lock, this is a no-op that returns {"ok": True, "skipped": "locked", ...} rather than blocking or raising — retry the call rather than assuming failure.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`plan_name`	Yes
`story_key`	Yes

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 17, 2026

TDQS

A5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully carries the behavioral burden. It discloses all side effects (ticket status, manifest status, stale parked_reason clearing, plan-completion notification), what it does not do ('does not merge or verify anything'), and lock behavior (no-op returning skipped instead of blocking). This is thorough and honest.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is longer than average but every sentence earns its place: side effects, parameter provenance, when-to-use, non-behavior, and lock semantics are all relevant. It front-loads the core action and then layers necessary detail without fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations, the description covers the full calling context: prerequisites, side effects, lock behavior, and parameter sources. An output schema exists, so return-value details are not required. Nothing critical is missing for an agent to select and invoke this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must add meaning. It does: plan_name is sourced from list_plans/save_plan/ingest_plan, and story_key is sourced from list_ready_stories/check_story_status/dispatch_story. This gives the agent exactly the provenance needed to fill both parameters correctly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Mark a story finished' with concrete effects on the ticket, manifest status, and parked_reason. It also differentiates itself from approve_merge by noting that approve_merge calls it internally, making the tool's unique role clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says when to call it directly ('only after the story's PR has actually been reviewed and merged'), when not to call it ('approve_merge already calls this internally'), and names the alternative path. This is exemplary usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.