FrontierMCP is an MCP server that exposes a markdown issue tracker under .scratch/ as a queryable graph, with eight tools for planning and tracking work.
List efforts — see each Effort, its Ticket count, and which header docs it holds.
View a board — one line per Ticket (id, title, kind, status, edges) with the Frontier marked; bodies are intentionally excluded.
Fetch ticket bodies — get full details for selected Ticket ids in one call, including legacy <effort>#<order> handles.
Create tickets — publish a whole breakdown atomically, with temporary keys for sibling edges, auto-numbering, repo-unique ids, cycle refusal, and optional Effort creation.
Update tickets — claim, resolve, or drop; replace blocked_by edges; set triage; add comments; tick acceptance criteria.
Edit an Effort Map — set Destination/Notes, add or graduate fog patches, rule items out of scope, with revision guards against concurrent overwrites.
Get/put a Spec — read or replace a whole opaque Spec document (e.g. YAML frontmatter) with expected_revision protection.
Migrate legacy tickets — normalize schema frontmatter, preserve or mint ids, convert prose edges to blocked_by, preview changes, and optionally rename files.
Flexible workspace resolution — defaults to the session working directory, supports FRONTIER_ROOT and per-call root overrides, and treats git worktrees as separate workspaces.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@frontier-mcp what issues are available to work on?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that serves the markdown issue tracker under .scratch/ as a queryable graph — so agents
stop re-parsing prose to learn what is open, blocked, or takeable.
Pre-1.0: the API can change in a breaking way on any release. The tool surface is fixed at eight
tools, but their arguments, results, and the on-disk conventions under .scratch/ are still being
settled — Ticket id format among them. Semver is honoured within 0.x as best it can be, and the
CHANGELOG.md records every break, but a 0.x bump is not a promise of compatibility. Pin an exact
version (see below) and read the changelog before moving the pin. From v1.0.0 on, breaking changes
wait for a major.
Related MCP server: brainforge-mcp
Node 20.20.2+ on 20.x, 22.17.1+ on 22.x, or 24.15.0+ on 24.x for frontier-mcp@0.4.0
Node 16.20.2+ to run the setup bootstrap; pnpm for development of this repository
Node 24 LTS is recommended for new installations. The package floors passed on macOS, Linux, and Windows in runtime CI.
Register FrontierMCP once in the client's user scope. The recommended setup downloads the bootstrap from the published 0.4.1 tarball, installs the exact 0.4.0 server outside your project, verifies its MCP handshake, and previews a Cursor user-scope entry before applying it. npm's current release is 0.4.1; the server stays pinned to 0.4.0 here because that is the exact version covered by the runtime measurements in the installation guide.
SETUP_DIR="$(mktemp -d)"
curl -fsSL https://registry.npmjs.org/frontier-mcp/-/frontier-mcp-0.4.1.tgz \
-o "$SETUP_DIR/frontier-mcp-0.4.1.tgz"
tar -xzf "$SETUP_DIR/frontier-mcp-0.4.1.tgz" -C "$SETUP_DIR" \
package/scripts/frontier-setup.cjs
node "$SETUP_DIR/package/scripts/frontier-setup.cjs" --version 0.4.0 --applyIt may run from a project pinned to Node 16; project runtime markers are evaluated later from the
client's working directory when the saved launcher starts. Omit --apply for a preview. For a manual
Cursor entry instead:
{
"mcpServers": {
"another-server": {
"command": "/absolute/path/to/another-server"
},
"frontier": {
"command": "npx",
"args": ["-y", "frontier-mcp@0.4.0"]
}
}
}Restart Cursor after saving. The pin is the version you get; updates remain manual.
The installation guide covers Node 16 projects, a PowerShell bootstrap, runtime managers, absolute desktop paths, Bun 0.4.0 support, Deno's Node fallback, other clients, updates, recovery, and removal.
Open the repository in your editor. FrontierMCP resolves the workspace from the session working
directory — walking upward to the nearest .scratch/, or .git in either form — so opening the
project is the only setup step. A git worktree is its own workspace: it carries .git as a file,
and it is served instead of the repository it was made from.
Read the tracker configuration document once: fetch MCP resource frontier://tracker-doc, or read
docs/agents/issue-tracker.md in a repo that vendors it.
Call list_efforts to see whether .scratch/ exists yet.
Call get_board on an Effort to see the Frontier, then get_tickets only for the ids you work.
A repository with no .scratch/ directory is not an error. Create the first Effort with
create_tickets, edit_map, or spec and create: true.
Optional, per call or per session:
Pass root on any tool call to read another directory.
Set FRONTIER_ROOT in the server environment for a non-standard layout.
The working directory is the one your client launched the server in, and it is fixed for the session.
Moving to another worktree mid-session does not retarget it — use root, FRONTIER_ROOT, or restart
the server.
Eight tools: list_efforts, get_board, get_tickets, create_tickets, update_ticket,
edit_map, spec, migrate_effort. See the tracker configuration document for when to use each.
pnpm install
pnpm test
pnpm run check
pnpm run build
pnpm run test:runtime
FRONTIER_NODE16=/path/to/node16 FRONTIER_NODE24=/path/to/node24 pnpm run test:setup
node src/bin.tsPublishing is CI-only via release-it. There is no local publish script, and adding one would mean minting the long-lived npm token that the CI setup exists to avoid.
Merge the work you want to ship to master.
On GitHub: Actions → Release → Run workflow, pick auto / patch / minor / major.
auto is the default and derives the bump from the conventional commits since the last release —
feat: gives a minor, fix: a patch. Pick an explicit one to override it. If nothing since the
last tag is releasable, auto exits green having shipped nothing, so confirm a new tag appeared.
The workflow runs checks + tests, bumps package.json, updates CHANGELOG.md, tags
v*, creates a GitHub Release, and publishes to npm with pnpm.
Replace the current frontier-mcp@0.4.0 pin in your user MCP config with the exact version you
released when you want the new build — pins stay manual on purpose.
The workflow is dispatchable from any branch but refuses to run off master: release-it commits,
tags and pushes as part of the run, so a release from a feature branch would rewrite that branch.
Local dry-run (no tag, no publish). It needs a clean working tree and an upstream branch, so commit first:
pnpm run release:drynpm publishing uses Trusted Publishing — GitHub Actions OIDC, configured for this repo on
npmjs.com, so there is no NPM_TOKEN to rotate.
Before changing .release-it.json or the workflow, read the release-it bullet in
AGENTS.md Work Guidance. Several settings there look removable and are not — the
absent registry-url, npm.skipChecks, npm.publishArgs, and the pnpm 10 pin each exist for a
reason recorded in one place so it cannot drift.
MIT — see LICENSE.
Publish a whole breakdown in one call. Edges may name a sibling by a temporary key you choose; the server mints repo-unique ids, numbers the files, and resolves the keys atomically — a partial failure creates nothing. Cycles are refused. An unknown Effort needs create.
| Name | Required | Description | Default |
|---|---|---|---|
| root | No | Workspace directory. Defaults to the session workspace. | |
| create | No | Start the Effort if the workspace does not hold it. Otherwise an unknown slug fails. | |
| effort | Yes | Effort slug to create them in. | |
| tickets | Yes | The whole set, in the order they should be numbered. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial context beyond annotations: atomic all-or-nothing ('a partial failure creates nothing'), repo-unique id minting, file numbering, key resolution, cycle refusal, and the create flag requirement. These are non-obvious, decision-relevant behaviors an agent cannot infer from the schema or annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences with no filler; the purpose is front-loaded, and every clause adds behavioral or parameter insight, from atomicity to cycle refusal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a bulk-create tool with dependencies and an all-or-nothing guarantee, the description covers failure semantics, key resolution, effort handling, and ordering. A small gap is the lack of any statement about return values; however, there is no output schema, and the core invocation behavior is fully specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description enriches parameter meaning by explaining that 'key' is a temporary, never-stored name, that 'blocked_by' can reference such keys, and that ticket order controls numbering. This connects the schema fields to the atomic key-resolution behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states a specific verb and resource: 'Publish a whole breakdown in one call' – creating a set of tickets in an Effort atomically. The behaviors described (minting ids, numbering files, resolving keys) clearly differentiate it from siblings like update_ticket or get_tickets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is the bulk-creation tool ('whole breakdown in one call'), but it does not explicitly state when to prefer it over update_ticket for single changes or how it relates to the other siblings. It does give one concrete conditional: an unknown Effort requires the create flag.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a Map's Destination and Notes, or edit one typed section — set Destination or Notes, add or graduate a fog patch, rule something out of scope — without rewriting the others. Decisions-so-far is generated from resolved Tickets and never accepted as input. Mutations pass expected_revision from a prior read so concurrent sessions cannot clobber each other.
| Name | Required | Description | Default |
|---|---|---|---|
| root | No | Workspace directory. Defaults to the session workspace. | |
| notes | No | Replace the Notes section. | |
| create | No | Start a missing Effort and its Map. Only for Effort/Map that do not exist yet — not a flag to send on every call. Does not change revision rules for mutations on an existing Map; create with no section fields reads an existing Map like a plain read. | |
| effort | Yes | Effort slug whose Map to read or edit. | |
| add_fog | No | Append a fog patch under Not yet specified. | |
| rule_out | No | Append a hand-ruled item under Out of scope. Never touches Decisions-so-far. | |
| destination | No | Replace the Destination section. | |
| graduate_fog | No | Remove a fog patch matched on its text. Fails when none match. | |
| expected_revision | No | Revision from a prior edit_map read. Required when overwriting an existing Map; omitted when creating one. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as destructive and non-idempotent; the description adds genuinely useful behavior beyond that: expected_revision provides optimistic concurrency so concurrent sessions cannot clobber each other, and Decisions-so-far is always derived from Tickets rather than accepted as input. This meaningfully discloses important side effects and invariants.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three tight sentences with no filler: the first front-loads the read/edit capability and operation types, the second states a key invariant, and the third explains the revision requirement. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a nine-parameter tool with full schema descriptions and no output schema, the description covers the essential context: partial edits, the Decisions-so-far invariant, and the expected_revision concurrency mechanism. It could slightly expand on what a read response contains, but 'Read a Map's Destination and Notes' plus the revision requirement gives the agent enough to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline baseline is 3. The description adds extra meaning by explaining the concurrency role of expected_revision and by explicitly stating that Decisions-so-far is never accepted as input, which helps the agent understand an important non-obvious constraint not encoded in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific resource ('Map') and a specific verb set ('Read ... or edit one typed section'), then lists concrete operations: set Destination or Notes, add/graduate a fog patch, rule out of scope. This clearly differentiates edit_map from sibling ticket-centric tools like create_tickets and update_ticket.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: use it to read the Map's sections or make a single typed edit without rewriting the others, and never to supply Decisions-so-far. It does not explicitly name alternative sibling tools or say when not to use it, but the edit-versus-read framing and mutation constraints provide solid usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
An Effort's Destination, then one line per Ticket — id, title, kind, status, Edges — with the Frontier marked. Never returns bodies; fetch those with get_tickets.
| Name | Required | Description | Default |
|---|---|---|---|
| root | No | Workspace directory. Defaults to the session workspace. | |
| effort | Yes | Effort slug, as reported by list_efforts. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful behavioral detail beyond the readOnlyHint: the output is intentionally limited to one line per ticket and never includes bodies, which is important scoping context. No contradiction with the annotations, and read-only behavior is already covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences with no filler: the core output shape is up front and the bodies caveat arrives immediately afterward. Every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the read-only annotation, 100% schema coverage, and simple required parameter (effort), the description tells an agent what it will get and explicitly what it will not get. It doesn't elaborate on 'Destination' semantics, but the sibling set and schema cover the remaining calling context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the params (root and effort) are already documented. The description clarifies output behavior but does not add new meaning to the parameters themselves; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the resource ('An Effort's Destination') and the exact output shape (one line per Ticket with id, title, kind, status, Edges; Frontier marked). It also distinguishes itself from get_tickets by explicitly noting it never returns bodies, so an agent can select it correctly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: it returns board-style summaries for an effort and explicitly directs body-fetching to get_tickets. It does not enumerate all alternatives (e.g., list_efforts, edit_map), so it stops short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full bodies for a list of Ticket ids, in one call. Use after get_board, only for the Tickets you actually work.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | Yes | Ticket ids, e.g. ["T12","T14"], resolved repo-wide. A Legacy Ticket with no id is fetched by the <effort>#<order> handle its Board line shows. | |
| root | No | Workspace directory. Defaults to the session workspace. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is known. The description adds useful context about batching ('in one call') and about resolving legacy ticket handles, but it does not disclose failure behavior or limits when invalid ids are passed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler. The most important scoping instruction is front-loaded and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only batch-fetch tool with a complete parameter schema and safety annotations, the description is adequate. It lacks an explicit output shape description, but no output schema exists and the tool is simple enough that this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents ids and root. The description's phrase 'Full bodies' hints at return semantics rather than adding new parameter meaning, so it meets but does not exceed the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Full bodies for a list of Ticket ids, in one call'. It clearly distinguishes this from the sibling get_board by framing get_tickets as the detail-fetch step after board listing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit sequencing ('Use after get_board') and call-scoping guidance ('only for the Tickets you actually work'). It does not name alternatives like update_ticket or create_tickets, but the primary routing decision is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the Efforts in a repo, each with its Ticket count and which header docs it holds.
| Name | Required | Description | Default |
|---|---|---|---|
| root | No | Workspace directory. Defaults to $FRONTIER_ROOT, then the session working directory. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already establishes the safety profile, and the description adds useful behavioral context by specifying what the result contains: each Effort's ticket count and header docs. For a simple read-only tool with no output schema, this is meaningful disclosure beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One compact sentence states the operation, scope, and key output fields with no filler. The most important information is front-loaded, and every element earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity, read-only tool with a single optional parameter, this description is complete: it says what the tool returns and where it operates. Since there is no output schema, covering the essential return values in the description is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the single optional 'root' parameter is already described in the schema. The description's mention of 'repo' loosely reinforces that root points at the workspace directory, but it adds no substantial parameter-level meaning. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('List'), resource ('Efforts'), scope ('in a repo'), and the returned information ('Ticket count' and 'header docs'). This clearly distinguishes it from siblings like get_tickets or get_board, which focus on different resources or views.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied: call this when you need a high-level list of Efforts with their ticket counts and header-doc ownership. However, it never explicitly names alternatives or states when not to use it, so the guidance is limited to what the purpose statement already conveys.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Normalize Legacy Tickets in an Effort: schema frontmatter, preserve existing ids, mint ids for Tickets that have none, turn prose Edges into blocked_by. Preview writes nothing. Filename rewriting is opt-in. Unrecognized files in the Effort directory are ignored.
| Name | Required | Description | Default |
|---|---|---|---|
| root | No | Workspace directory. Defaults to the session workspace. | |
| effort | Yes | Effort slug whose Legacy Tickets to normalize. | |
| rename | No | Rename files to <NN>-T<n>-<slug>.md. Off by default so relative links keep resolving. | |
| preview | No | Report every change and write nothing. Defaults to false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false, and the description adds valuable context: preview writes nothing, filename rewriting is opt-in with a link-preservation rationale, unrecognized files are ignored, and id/edge handling rules are spelled out. This goes well beyond the annotation flags without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four tight sentences front-load the core purpose, then highlight the two safety/decision-critical behaviors (preview, rename opt-in), and close with a clear boundary for unrecognized files. No redundant wording or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description sufficiently covers what the tool does, the safe preview mode, the opt-in rename behavior, and the handling of unrecognized files. The destructive nature is carried by the annotation and reinforced by the preview note. Minor omissions like return format or transactional guarantees are acceptable given the simple required-parameter surface and strong schema coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema documents all four parameters at 100% coverage, including defaults and behavioral implications (e.g., rename off by default, preview defaults to false). The description reinforces the rename and preview behaviors but adds only marginal meaning beyond the schema. With such high schema coverage, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb ('Normalize') and resource ('Legacy Tickets in an Effort'), then lists concrete transformations: schema frontmatter, id preservation/minting, and prose-edge conversion. This clearly differentiates it from sibling CRUD tools like create_tickets or update_ticket, which operate on new or existing ticket state rather than legacy format migration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose statement makes it obvious when to use this tool—when there are legacy tickets in an Effort that need normalization. It also highlights that preview mode writes nothing, giving a clear safe-usage path. It doesn't explicitly name alternatives or state when not to use it, but since no sibling offers migration functionality, the usage context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get or put a Spec as a whole opaque document (conventionally with YAML frontmatter). Nothing edits a Spec section by section — an Effort may hold both a Map and a Spec. Puts pass expected_revision from a prior read so concurrent sessions cannot clobber each other.
| Name | Required | Description | Default |
|---|---|---|---|
| root | No | Workspace directory. Defaults to the session workspace. | |
| create | No | Start the Effort and its Spec if neither exists. Otherwise an unknown slug fails. | |
| effort | Yes | Effort slug whose Spec to get or put. | |
| content | No | When set, replace the Spec wholesale (conventionally a document with YAML frontmatter). When omitted, return the current document. | |
| expected_revision | No | Revision from a prior spec read. Required when overwriting an existing Spec; omitted when creating one. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description discloses meaningful behavior: the Spec is an opaque whole document, section-by-section editing is not possible, and Puts require expected_revision from a prior read to prevent concurrent clobbering. This is substantial behavioral context, not a restatement of annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences, front-loaded with the core action, and every sentence earns its place. The YAML frontmatter note, the Map contrast, and the concurrency protection are all useful and non-redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With all parameters documented in the schema, the description covers the main behavioral nuances: whole-document semantics, no section editing, and revision-based concurrency. Since there is no output schema, a note on the exact return shape for a get (document plus revision) would make it fully complete, but the current definition is sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining that the document is opaque, conventionally YAML frontmatter, and that expected_revision comes from a prior read to enable concurrency safety. This deepens meaning beyond the schema without needing to repeat parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear and specific: “Get or put a Spec as a whole opaque document” names the resource, the action, and the granularity. The line “an Effort may hold both a Map and a Spec” helps distinguish it from sibling tools like edit_map.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use the tool: whole-document Spec reads/writes, with “Nothing edits a Spec section by section” ruling out section-level edits. It does not explicitly name an alternative tool like edit_map, but the Map/Spec contrast gives enough routing context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change one Ticket. Lifecycle: claim, resolve with a one-line gist, drop with a reason, reopen with a reason, or release a claim — at most one of those per call. Graph: replace the Edges, refused if they close a cycle. Identity: title, kind, and type. Annotations: triage role, a comment, ticking acceptance criteria; these touch no part of the graph. Any of the four groups may accompany the others or stand alone.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Ticket id, or the <effort>#<order> handle of a Legacy Ticket. | |
| drop | No | Close the Ticket as work ruled out of scope. | |
| kind | No | Replace the Ticket kind. | |
| root | No | Workspace directory. Defaults to the session workspace. | |
| tick | No | Acceptance criteria to check off, matched on their text. Wrapped criteria match both as get_tickets returns them and re-joined onto one line. All references resolve before anything is written — one unmatched name fails the whole call and leaves the file untouched. | |
| type | No | Replace the decision type — research, prototype, grilling, or task. | |
| claim | No | Take the Ticket. Fails if another holder already has it. | |
| title | No | Replace the Ticket title. | |
| reopen | No | Return a resolved or dropped Ticket to open. | |
| status | No | Not settable directly — use claim, resolve, drop, reopen, or release. Named here to say so. | |
| triage | No | Set the triage role. A separate field from status; neither touches the other. | |
| comment | No | Append to the comment log, stored exactly as written. | |
| release | No | Release the claim on a claimed Ticket and return it to open. Pass { release: true }. | |
| resolve | No | Close the Ticket as a step on the route. | |
| blocked_by | No | Replace the Edges outright, each a plain Ticket id resolved repo-wide. An empty list clears them. A cycle is refused. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true, and the description adds substantial behavior: 'at most one' lifecycle change per call, graph replacements refused on cycles, annotations touching no part of the graph, and transactional reference resolution ('leaves the file untouched'). It fully discloses atomicity and failure semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense yet well-structured, front-loaded with the core action and then organized by change group. No sentence is wasted; each adds a distinct constraint or clarification.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high complexity (15 params, nested objects, no output schema), the description covers the major behavioral constraints and failure modes well, including atomicity and cycle refusal. Minor gaps remain: no explicit note about return values or atomicity when multiple non-reference validation failures occur, but the description is still remarkably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds meaningful interaction context: status is 'not settable directly', blocked_by replacement behavior with cycle refusal, tick matching rules, and grouping of parameters into coherent semantic groups. This goes beyond the schema's individual parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Change one Ticket,' a specific verb and resource, then enumerates the four distinct change groups: lifecycle, graph, identity, and annotations. This clearly differentiates it from siblings like create_tickets (creation) and edit_map (map-level editing).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no when-to-use guidance against alternatives. It never mentions create_tickets for new tickets or edit_map for graph-wide changes, and it gives no exclusions or prerequisites. The usage context is only implied by the phrase 'Change one Ticket.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.4.1create_tickets1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"edit_map1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"get_board1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"get_tickets1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"list_efforts1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"migrate_effort1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"spec1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"update_ticket7 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / properties / kindAdded value: +{
+ "description": "Replace the Ticket kind.",
+ "enum": [
+ "build",
+ "decision"
+ ],
+ "type": "string"
+}Input schema / properties / releaseAdded value: +{
+ "const": true,
+ "description": "Release the claim on a claimed Ticket and return it to open. Pass { release: true }.",
+ "type": "boolean"
+}Input schema / properties / reopenAdded value: +{
+ "description": "Return a resolved or dropped Ticket to open.",
+ "properties": {
+ "reason": {
+ "description": "Why it is being reopened.",
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "reason"
+ ],
+ "type": "object"
+}Input schema / properties / status / descriptionPrevious value: -"Not settable directly — use claim, resolve, or drop. Named here to say so."New value: +"Not settable directly — use claim, resolve, drop, reopen, or release. Named here to say so."Input schema / properties / titleAdded value: +{
+ "description": "Replace the Ticket title.",
+ "minLength": 1,
+ "type": "string"
+}Input schema / properties / typeAdded value: +{
+ "description": "Replace the decision type — research, prototype, grilling, or task.",
+ "minLength": 1,
+ "type": "string"
+}v0.2.1edit_map1 field changedInput schema / properties / create / descriptionPrevious value: -"Start the Effort and its Map if neither exists. Otherwise an unknown slug fails."New value: +"Start a missing Effort and its Map. Only for Effort/Map that do not exist yet — not a flag to send on every call. Does not change revision rules for mutations on an existing Map; create with no section fields reads an existing Map like a plain read."update_ticket1 field changedInput schema / properties / tick / descriptionPrevious value: -"Acceptance criteria to check off, matched on their text."New value: +"Acceptance criteria to check off, matched on their text. Wrapped criteria match both as get_tickets returns them and re-joined onto one line. All references resolve before anything is written — one unmatched name fails the whole call and leaves the file untouched."v0.1.0create_ticketsedit_mapget_boardget_ticketslist_effortsmigrate_effortspecupdate_ticketScored across 8 tools
Each tool targets a distinct resource or action: get_tickets fetches bodies, get_board provides an overview, create_tickets does batch creation, update_ticket handles single modifications, edit_map and spec manage different document types, and migrate_effort is a utility for normalization. No two tools have overlapping purposes.
Most tools follow a consistent verb_noun snake_case pattern (get_tickets, list_efforts, create_tickets, update_ticket, edit_map, migrate_effort). The lone exception is 'spec', which uses a bare noun instead of a verb, creating a minor inconsistency but remaining clear and predictable.
With 8 tools, the server is well-scoped for its purpose of managing efforts, tickets, maps, and specs. Each tool serves a distinct function without redundancy, and the count is squarely within the optimal 3-15 range.
The core ticket lifecycle is covered (batch create, single update, read via board and bodies), along with map and spec editing and migration. The main gap is the lack of a delete or archive tool for tickets, and there is no explicit create_effort tool, though create_tickets references needing one. These are minor gaps given the planning-centric focus.
Minimal issue tracker: projects, objectives and trackable plans, written by agents over MCP.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Repository knowledge graph MCP server for codebase understanding and debugging.
Agent-native MCP server over the public saagarpatel.dev corpus. Read-only, stateless.
