Click on "Install 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., "@feature-tracker-mcp what approvals are waiting for me?"
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.
A project-agnostic tracker for the case where one person directs several AI coding sessions at once and has become the bottleneck.
The problem is not "track features." It is: several tracks are in flight, each session is blind to the others, decisions surface constantly, and reading everything is the job. Most of those decisions are mundane and delegable. A few are genuinely yours. Nothing separates them, so you read all of it.
Each project gets its own Postgres instance in a .oz folder — the project owns its tracker outright.
Related MCP server: Brain MCP
Goals are objectives, not filing labels. Each carries what is being achieved, what done means, what is deliberately excluded, and what constrains it. A worker reads its goal before starting and declines work that falls inside the non-goals — that is the difference between executing a queue and pursuing an objective.
Features belong to exactly one goal. Ids are allocated atomically (DIP-17, GLG-4) and never change, so anything citing one in a commit message keeps resolving. They carry acceptance criteria, dependencies, and a parity record.
Gates are decisions a session must not take alone — architectural, install, spend, irreversible. Raising one banks the question and moves on; the principal answers a round of them in one sitting.
Parity is tracked across eight dimensions, because work is only done when it is done in all of them: code, unit tests, functional tests, documentation, screens, builds, infrastructure, features.
Studies are investigations whose deliverable is a document and a decision. Pre-registered, and allowed to conclude "do not build this".
Conferrals are the record of Claude working a judgement out with a peer model — ChatGPT, a harder-thinking Claude, DeepSeek. Every goal, feature, study, checkpoint and finished diff requires one, enforced by the tools rather than requested by the docs.
Driven through the /oz skill.
Command | Does |
| What can be worked now — not done, nothing it depends on outstanding |
| What is waiting, and on what |
| Drive a goal's features to done, here |
| Spawn the backlog maintainer and a worker per goal, each in its own worktree |
| Cross-track state, including uncommitted work per worktree |
| Broadcast to every worker, including ones not yet running |
| Wind down leaving it resumable: stash every worktree, record where. |
| Work interrupted by a shutdown, and putting it back |
| Who is alive, how long since each was heard from, what each holds |
Command | Does |
| Both passes in order — goals, then the features under them. The order matters: criteria written under an unrefined goal are written against nothing |
| Draft and record every unrefined goal in one pass; gate what the docs cannot settle |
| Give every open feature acceptance criteria in one pass |
| Define a new goal — the conversation produces the name |
| Work through a derived checklist a page at a time |
| Project-wide coverage analysis — what nothing tracks, including goals that should exist. The scoped forms bound what is filed, not what is examined |
| What the project is not |
| Invention, ending in one checkpoint |
| Investigate; deliverable is a document and a recommendation |
| Record something that would otherwise be lost |
| Record a dependency |
Command | Does |
| Watches, and prompts you with the pending gates as a pickable checklist. The only path from a raised gate to a decision |
| The gate queue |
| Counts, items, the append-only record |
| Coverage, and the cheap probe that populates it |
| Goals and hygiene |
| Dump, list, and restore the tracker — take one before any bulk pass |
One reasoner cannot find its own blind spot, and the principal cannot always supply one. When the question is a derivation they would have to take on trust, asking them is not review — it is handing over an unread liability. That is the problem this exists to solve.
A conferral is an exchange, not a verdict. It runs rounds: put the actual draft and reasoning to the peer, settle what it says it lacked, check what it asserts, disagree where you disagree, keep going while it is still converging, stop when circling. How it ends decides who hears about it.
Outcome | Consequence |
| Recorded. The principal is not involved |
| The peer moved Claude and the change was applied. Recorded with what changed |
| Promoted to the principal, carrying both positions |
Soft gates never reach the principal. architectural and install forks are raised into the loop — gate_raise refuses one with no conferral, because escalating instead of thinking is what made the queue unreadable. spend and irreversible are always the principal's: two models agreeing is not authorisation to spend someone's money or to take an action with no undo.
The peer drafts where it should. Study pre-registration is written by the peer and attacked by Claude, because a method is attacked best by whoever did not write it, and the falsifier is the question a single reasoner is least able to ask itself.
A feature cannot reach done until its diff has been through a peer — checked against the database, not asserted in the same call that closes the work.
Enforcement is mechanical because prose failed. The actor field has accepted the value chat since the first commit and across 76 recorded events has never once held it. A mechanism that recommends conferral is a mechanism that gets skipped.
The framing is kept verbatim. Claude chooses what the peer sees, so agreement can be manufactured with a leading question — and from outside, that is indistinguishable from independent agreement. asked and the peer's own account of what it lacked are what make it distinguishable.
Agent | Does |
| One per goal, own worktree. Claims, builds, evidences, releases. Refines its own items and gates only genuine forks |
| What a worker structurally cannot: dependencies across goals, cross-goal duplication, staleness |
| Per turn, cheap model. Records what a turn implied that would otherwise be lost |
| Dedups; splits what peers can settle from what only the principal can |
| Investigates, writes it up, links what it spawned and killed |
No agent may call gate_decide. An agent approving its own gate makes the mechanism theatre.
git clone https://github.com/spe-investigator/feature-tracker-mcp.git
cd feature-tracker-mcp
.\install.ps1Builds, copies the /oz skill and the agents into ~/.claude, and registers the server. Requires Node 18+ and Docker; the database is created in the project's .oz folder on first use, and Docker is started automatically if it is not running.
The database is the state, and the bus. Sessions cannot see each other, so coordination goes through Postgres rather than messages: a message is lost if its recipient is not running, and unauditable afterwards. Messaging is at most a doorbell.
Ids are allocated atomically. Two sessions reading a file, seeing the next free number and both taking it is how duplicate migration numbers happen. A counter incremented inside the inserting transaction makes it impossible.
Claims are leases, not flags. A worker that dies holding a flag blocks its feature forever; a lease expires and the work returns to the pool.
Counts are two numbers, never a ratio. The numerator is what converged; a growing denominator means real work was found. 12/16 → 12/20 reads as 75% → 60% — a drop — when nothing regressed and two genuine issues were named.
Standup reads working trees, not just commits. Measured here: every worktree reported zero commits ahead while two held real uncommitted work — a new crate in one, four untracked files in another. A standup built on git history calls active tracks idle.
Rejection means two things. "Not for this goal" is a routing error and the feature is moved; "not wanted" is a decision about the project. Only the second suppresses re-derivation. Every refusal keeps its rationale, and accumulated they define what the project is not — the difference between "no" and "no, because we decided X".
Drafting is derivable; decisions are not. Refinement is a batch pass over everything, with gates raised only for what the documents cannot settle. A flow that asks a question per item spends attention on the part that needed no input.
Studies are pre-registered. Method, decisive evidence and falsifier are recorded before execution, because a method chosen after seeing the data can be selected for the answer it produces. Revisions are counted rather than silent.
Thresholds are measured, not guessed. Duplicate detection uses trigram similarity at 0.30 — real restatements score 0.45–0.63, unrelated titles under 0.10, and an initial guess of 0.45 let a genuine duplicate through at 0.449.
Backups are verified, not just written. A dump is read back before it is reported as taken — the expected tables must be present and the file non-trivial. pg_dump can exit zero having written almost nothing, and an unverified dump is a file rather than a backup.
The schema has no migrations. All DDL lives in src/db.ts as idempotent statements applied on every connect, so a schema change ships with the code that needs it and lands the moment any session connects. The cost is that nothing records when a change landed, there is no down-migration, and anything destructive — dropping a column, narrowing a type — has no safe expression in this pattern and needs a real migration path first.
An objective is lifted once, not re-derived. Goals carry doc_ref — the file and heading their objective came from — and refined_commit, the tree it was read at. Without the pointer a refine pass has to re-read the whole source document to locate each goal's section, once per goal, and afterwards nothing distinguishes an objective taken from the document from one invented where the document was thin.
Incorporation, not annotation. converged_after_revision requires stating what changed, and the tool refuses the outcome without it. Feedback logged beside an unchanged draft changes nothing and reads as diligence — which is worse than not conferring, because it looks like the mechanism worked.
Derivation is goal-scoped; gap analysis is not. derive_features asks what one objective implies, so it can only find work inside a goal somebody already wrote. Work between two goals, or outside all of them, is invisible to it by construction — and a missed feature inside a goal surfaces the next time anyone reads that goal, while a missing goal never surfaces at all. /oz gaps is the only thing looking from far enough back to find one, and a missing goal is a hard gate because gate_reopen cannot unwind a goal that already has work routed into it.
A gate blocks work, and answering one has to unblock it. gate.blocks was written from the first commit and read by nothing, so a feature whose blocking question was unanswered was still handed out and coded straight past. feature_ready now skips those and reports them rather than hiding them; feature_unblocked is what a resuming worker calls, because answering a gate changes a gate row and nothing else.
/oz start has never been executed. The spawn line is documented but background spawning is untested here. Try /oz task on one goal first.
The interactive flows are unrun. /oz refine, /oz design, /oz study and /oz goal are written and their tools are tested individually; the conversations are not.
Parity probes exist for documentation and code only. builds and infrastructure need a real check — a build, an applied migration — and a reference search would only pretend to answer them. screens is switched off.
No test suite. The conferral enforcement has 11 passing checks; nothing else does.
The conferral loop has never been run for real. The enforcement is tested against fabricated conferrals, which is exactly what it cannot detect. Whether the exchanges actually happen is a property of the sessions, not of this code.
The markdown renderer that would regenerate a human-readable tracker from the database does not exist, so a migrated markdown tracker cannot be diffed against the database to prove nothing was lost.
Record everything agreed in one design session, in a single transaction. A design conversation produces features, risks, data sources and decisions together and they only make sense together; recording them one call at a time leaves a half-captured design if anything fails, and nothing afterwards can tell which rows came from that sitting. Duplicates are reported rather than skipped or forced — being told 'three of your fourteen already exist' is information the design session should see.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| goal | No | The goal the session was about, if it was about one. | |
| note | No | What the session concluded, in a sentence or two. | |
| actor | No | ||
| items | Yes | Everything the session agreed on — not just the features. | |
| conferral | No | Required. One conferral for the sitting. A design is argued as a whole — whether the pieces fit, what it left out — not item by item. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the burden. It discloses atomicity (single transaction, leaving no half-captured design) and duplicate handling (reported, not skipped or forced), both important call-time behaviors.
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 first sentence front-loads the action and scope; the subsequent sentences add meaningful behavioral and rationale content. Slightly wordy, but 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 tool with nested objects and no output schema, the description adequately explains the overall contract and failure behavior. However, it never mentions the required conferral sub-object, leaving an agent to discover it solely through the schema; the schema is rich enough to compensate.
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 high (83%), including rich descriptions for items and conferral, so the description does not need to restate parameters. The only gap is that it doesn't clarify the undocumented actor field, but baseline 3 applies when the schema does most of the work.
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 action (record) and exact scope (everything agreed in one design session) and frames it as a single transaction. It distinguishes itself from per-item sibling tools by explaining that design artifacts only make sense together.
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 states the when: at the end of a design session, all agreements should be recorded atomically. It implies the alternative of recording one item at a time is wrong, but it does not explicitly name or exclude sibling tools like feature_propose or confer_record.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Whether the peer channel is earning its place: where it changed the answer, and where it could not settle something. Both halves are reported, because showing only the first would make the mechanism unfalsifiable.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the disclosure burden. It does add useful behavioral context by stating that both positive and negative outcomes are reported and that this is deliberate for falsifiability. However, it does not disclose whether the tool is read-only, whether there are side effects, or what the returned digest concretely contains.
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 two sentences with no filler, and the second sentence usefully explains why both halves are reported. It is somewhat indirect and jargon-heavy, but it remains compact and every sentence contributes.
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 one-parameter, read-only-looking digest, the description provides the gist and the reporting philosophy. However, with no output schema, it leaves the concrete return format, field names, and interpretation of 'could not settle' unspecified, and the domain-specific term 'peer channel' could confuse an agent without additional 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?
The only parameter, cwd, is fully documented in the schema with 100% coverage, so the description does not need to compensate. The description adds no parameter-specific meaning beyond the schema, which meets the baseline for full schema coverage.
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 communicates an evaluative purpose: reporting both where the peer channel changed the answer and where it could not settle something. This distinguishes it from raw event tools like confer_record or confer_history, though it lacks an explicit imperative verb and relies on the metaphorical phrase 'earning its place.'
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?
No explicit when-to-use or when-not-to-use guidance is provided, and no alternatives such as confer_history or confer_record are mentioned. The intended use case is only implied by the phrase 'whether the peer channel is earning its place,' so an agent must infer when to call this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What a subject has been through with a peer, newest first. Omit both filters for the whole project. Read this before re-litigating something — an argument already had and settled is on the record here.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| limit | No | ||
| subject_id | No | ||
| subject_kind | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It does disclose ordering ('newest first'), scoping behavior ('Omit both filters for the whole project'), and hints that the output contains settled arguments on record. However, it leaves the 'peer' relationship undefined and does not mention response shape, side effects, or any access considerations.
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 short sentences with no filler: result and ordering first, scope instruction second, practical warning third. It is appropriately concise and front-loaded, though the first sentence is slightly awkward.
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 tool with no annotations, no output schema, and three mostly undocumented parameters, the description is too thin. It never defines the subject/peer model, the expected value of subject_id, or limit behavior, leaving an agent to guess at critical calling details.
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 only 25%; only cwd has a description. The phrase 'Omit both filters for the whole project' adds useful semantics by implying subject_id and subject_kind are optional filters affecting scope. But it does not explain what subject_id refers to, how subject_kind constrains it, or what limit does, so the compensation is partial.
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 phrase 'What a subject has been through with a peer' gestures at history retrieval but is vague: 'subject' and 'peer' are never defined, and there is no explicit verb like 'list' or 'return.' The 'newest first' ordering helps, but the description does not distinguish this from siblings like confer_digest or feature_history.
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 a concrete when-to-use signal: 'Read this before re-litigating something' and clarifies that omitting both filters returns whole-project history. It provides clear context, though it does not mention alternatives or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record an exchange with a peer model as its own act. Use for a diff review before a feature is marked done — a worker cannot both review its own work and close it in one call, so the review has to exist first — and for any conferral worth keeping that is not attached to another write. The subject must already exist.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| conferral | No | ||
| subject_id | Yes | The feature id, goal name, study id, or gate id it concerns. | |
| subject_kind | Yes | 'diff' is the code review that gates a feature reaching done. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It does communicate that this is a recording act and explains sequencing ('a worker cannot both review its own work and close it in one call, so the review has to exist first'). However, it does not disclose what happens on success, failure modes when the subject does not exist, or how the recorded conferral can be retrieved later.
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 compact and front-loaded. The opening sentence states the core action, the second gives two concrete use cases, and the third gives the critical precondition. Every sentence earns its place; no filler or redundancy.
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 write tool with no annotations and no output schema, the description covers the essential contextual grounding: what the tool records, when to use it, why the record must precede feature completion, and the existence precondition on the subject. It does not explain the return value, but absence of an output schema lowers that burden. The rich parameter schema covers the remaining invocation detail.
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 75%, and the schema already contains detailed descriptions for most parameters, especially inside the nested 'conferral' object. The description adds little parameter-level meaning beyond 'The subject must already exist,' which is a useful precondition for subject_id but not a semantic elaboration. The baseline of 3 is appropriate because the schema does the heavy lifting.
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 and resource: 'Record an exchange with a peer model as its own act.' It clearly identifies the tool as a write/record action and gives concrete use cases (diff review before a feature is done, standalone conferrals). It does not explicitly name sibling tools like confer_history or confer_digest, so some sibling differentiation is left to inference.
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 when-to-use guidance: 'Use for a diff review before a feature is marked done' and 'for any conferral worth keeping that is not attached to another write.' It also states a necessary precondition: 'The subject must already exist.' It stops short of naming alternative tools or explicit when-not-to-use cases beyond the 'not attached to another write' clause.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dump the project's tracker to .oz/backups and verify it. Take one before any bulk change — a refine pass, a restore, a migration. A dump restores anywhere, unlike a copy of the data directory, and the dump is checked before being reported as a backup: an unverified backup is a file, not a backup.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| label | No | Why it was taken, e.g. 'pre-refine'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses that the dump is written to .oz/backups, is portable ('restores anywhere'), and crucially is verified before being reported — 'an unverified backup is a file, not a backup.' It does not cover failure modes or permissions, but the core safety behavior is well disclosed.
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 sentences, each earning its place: the action, the timing, and the verification/portability principle. The core command is front-loaded and there is no filler.
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 backup tool with optional params and no output schema, the description covers what it does, where it writes, when to use it, and how success is determined. It could be more explicit about return values or error behavior, but an agent has 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 description coverage is 100%, so the schema already documents cwd and label. The description adds contextual color about when backups are appropriate, but does not add parameter-specific semantics beyond what the schema provides.
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 and resource: 'Dump the project's tracker to .oz/backups and verify it.' This clearly identifies the operation, its target, and the verification step, and the action is distinct from reading or listing backups (db_backups) or restoring them (db_restore).
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?
It gives explicit timing guidance: 'Take one before any bulk change — a refine pass, a restore, a migration.' It also contrasts with copying the data directory, but it does not name or explicitly exclude sibling tools such as db_restore or db_backups, so the alternatives guidance is only partial.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Backups on disk, newest first.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the burden. It does disclose that backups are stored on disk and returned newest first, but it does not state whether the operation is side-effect-free, what a backup entry contains, or what happens when no backups exist.
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 only four words, all of which are meaningful, and the key ordering behavior is front-loaded. There is no filler or redundant restatement of the tool name.
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 tool with one optional parameter and no output schema, this is minimally viable: it states where backups live and the sort order. However, without an output schema, it does not describe the shape of a backup entry or behavior on no backups, so an agent must infer the return format.
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 cwd parameter is already fully documented in the schema. The description adds no further parameter-level meaning beyond what is provided.
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 identifies the resource ('backups') and the key ordering behavior ('newest first'), and the plural name distinguishes it from the sibling db_backup. However, there is no explicit verb such as 'list' or 'retrieve', so the action is implied rather than stated.
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?
No guidance states when to call this over db_backup, db_restore, or stash_list. The description does not provide context, prerequisites, or alternatives; usage must be inferred from sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Restore a backup over the live tracker. DESTRUCTIVE and irreversible: it takes a safety backup first and refuses without confirm: true. Restoring the wrong file over a working tracker is the mistake with no undo.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| name | Yes | The backup filename, from db_backups. | |
| confirm | Yes | Must be true. This overwrites everything currently tracked. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full behavioral burden. It explicitly warns that the operation is DESTRUCTIVE and irreversible, discloses the automatic safety backup, and explains the confirmation gate. It also identifies the primary failure mode: restoring the wrong file leaves no undo.
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 short sentences lead with the action, then front-load the critical safety warning. Each sentence adds either scope or risk information, with no filler.
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 destructive restore tool with three fully documented parameters and no output schema, the description gives an agent everything essential: what the tool overwrites, why confirmation is mandatory, what safety mechanism exists, and the primary failure mode. Return-value documentation is not necessary for safe invocation here.
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 percent; every parameter already has a description, including the backup filename source, the confirm semantics, and the cwd default. The description reinforces the danger of confirm but adds no new parameter-level facts beyond the schema, so the 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 opens with a concrete verb and object: restore a backup over the live tracker. This clearly places it among the backup tools and distinguishes it from siblings like db_backup and db_backups by direction, and from stash_restore by naming backups explicitly.
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?
It establishes the invocation context—restoring a backup over the working tracker—and states the required guardrail: confirm must be true and a safety backup is taken first. It does not name alternatives or give when-not-to-use guidance, but the context is clear enough for this destructive operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Derive a feature checklist for a goal from the documentation and existing features, and put it straight in the backlog at 'proposed' — recorded, not yet agreed. Defining a goal must produce work, not just an objective. Call project_boundaries FIRST: re-proposing something already refused wastes a review round and teaches the principal that the queue does not learn. Candidates matching an existing feature are reported rather than created.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| goal | Yes | ||
| note | No | ||
| actor | No | ||
| source | No | What was read to derive these. | |
| candidates | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it discloses key side effects: records are placed in the backlog at 'proposed', not agreed, and candidates that match existing features are reported rather than created. It also exposes the prerequisite of calling project_boundaries first, which is valuable behavioral context.
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 tight and front-loaded: the core action is stated first, followed by the status implication, the rationale, and the required ordering with project_boundaries. Each sentence contributes either purpose, workflow, or behavior, with no wasted filler.
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?
The description covers the tool's role, side effects, deduplication behavior, and a prerequisite call, which is strong for a mutation tool with no annotations. However, it does not describe the return/value produced after invocation, and it leaves several parameters under-explained despite low schema coverage. It is adequate but has clear gaps.
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 only 33%, so the description must compensate for undocumented parameters. It mentions 'goal' and 'candidates' semantically and explains matching behavior, but it does not explain parameter meanings, how candidates should be structured, or what 'source' and 'cwd' contribute. The description adds little beyond the property names.
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 and resource: 'Derive a feature checklist for a goal from the documentation and existing features' and clarifies the exact disposition 'put it straight in the backlog at proposed'. It also distinguishes itself by explaining that matching candidates are 'reported rather than created', so an agent can separate it from feature_propose and similar siblings.
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 workflow context: call project_boundaries FIRST to avoid re-proposing refused work, and it frames derivation as a required output of goal definition ('Defining a goal must produce work'). However, it does not explicitly name when-not-to-use it or contrast it with alternative derive_* or feature_* tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record what a gap analysis found. Feature gaps land in the backlog at 'proposed' under one proposal, so derive_page/derive_review work on them unchanged. Goal gaps become HARD gates: creating a goal reshapes what every feature hangs off, and gate_reopen cannot unwind it once work routes in, so it stays the principal's however well the pair agrees. Call gap_scan first and check every candidate against the refusals it returns — a settled refusal is a decision, not an oversight. Finding nothing is a real outcome; record it as one rather than manufacturing candidates.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| note | No | ||
| actor | No | ||
| scope | No | What to record; defaults to all. Scope bounds what is FILED, never what was examined — both kinds of gap come out of one reading of the same frame, since you cannot tell a missing feature from a missing goal until you have decided whether an existing objective covers it, and that decision IS the analysis. Passing gaps outside the scope is refused rather than dropped: a finding already made must not be discarded to satisfy a filter. | |
| conferral | No | Required. ONE conferral for the whole analysis. Coverage is argued over the set — whether a seam between two objectives is real, whether something is genuinely uncovered or merely undocumented — and that argument does not decompose per candidate. | |
| goal_gaps | No | Work the project needs that NO existing objective covers. This is the finding nothing else in oz can produce, and the one that should be rarest — a non-goal is not a gap, it is the answer. | |
| feature_gaps | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure, and it does so strongly. It warns that feature gaps become 'proposed' backlog items, that goal gaps become HARD gates that gate_reopen cannot unwind once work routes in, and that a settled refusal from gap_scan is a decision rather than an oversight. These are exactly the consequential side-effects an agent needs to know before invoking a recording tool.
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 but efficient; nearly every sentence carries behavioral or sequencing value. It front-loads the core purpose with 'Record what a gap analysis found.' It is arguably a single dense paragraph rather than structured guidance, but given the complexity of the tool, the length is justified and there is little waste.
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?
The description covers the tool's most important caveats, but it does not specify how to represent a legitimate 'nothing found' outcome in the schema (empty arrays? a single call?), nor does it explain the returned result since there is no output schema. The schema provides strong parameter-level documentation, so this is not a fatal gap, but a complex tool with no output schema should give a bit more operational 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 57%, and the schema already documents most parameters richly. The description adds high-level meaning about why goal_gaps are consequential and how feature_gaps flow downstream, but it does not compensate for the undocumented parameters or clarify how to encode the 'finding nothing' outcome in terms of specific parameter values. This is adequate but not exceptional.
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 and resource: 'Record what a gap analysis found.' It then distinguishes the two artifact types (feature gaps vs goal gaps) and explicitly ties feature gaps to downstream sibling tools (derive_page/derive_review), so an agent can tell which output this tool produces and how it relates to nearby tools.
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 guidance: 'Call gap_scan first and check every candidate against the refusals it returns.' It also sets a clear policy for when recording nothing is appropriate, which is a form of when-to-use guidance. However, it does not explicitly name an alternative tool to use instead of derive_gaps in any situation, so the 'vs alternatives' dimension is only partially addressed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Derivations and how far each review has got.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| goal | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description alone must disclose behavioral traits. It only adds that the output concerns 'how far each review has got'; it does not state whether the operation is read-only, how results are scoped or ordered, whether it can be expensive, or what failures are possible.
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 short and contains no filler, but the brevity is under-specification, not effective structure. It is a fragment with no verb and no clear organization of 'what is listed' versus 'what progress information is returned'.
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?
There is no output schema and no annotations, so the description must carry return semantics. 'Derivations and how far each review has got' is too vague to be actionable: the meaning of 'review', the role of the goal parameter, and the precise form of progress are all missing.
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?
With 50% schema coverage, the description needed to compensate for the undocumented goal parameter, but it does not. It neither explains how cwd or goal filter the result nor relates the term 'review' to either parameter.
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 identifies the topic—derivations and review progress—so it is not a pure tautology. However, it is a noun phrase rather than a statement of action; it never says it lists or returns anything, and it does not distinguish derive_list from sibling derive_* tools such as derive_review or derive_features.
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?
There is no explicit or implicit guidance about when to call this tool instead of alternatives. It does not mention a use case, exclusions, or prerequisites, and the large set of sibling derive_* tools makes the choice ambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A page of a derivation still awaiting review. Deliberately small — a long list gets skimmed, and a skimmed checklist is worse than none because it looks reviewed.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| page | No | ||
| per_page | No | Default 8. | |
| include_decided | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It does add one meaningful trait: results are deliberately small to avoid superficial review, and the page is limited to items still awaiting review. But it does not state whether the operation is read-only, whether it alters review state, how filtering works, or what the response contains.
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 only two sentences and front-loads the core idea before offering rationale. The second sentence earns its place by explaining why small pages matter, though the poetic phrasing could be more operationally direct.
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?
The tool has five parameters, no output schema, and no annotations, so the description must carry significant explanatory weight. It leaves the meaning of required 'id', the role of 'cwd', the behavior of 'include_decided', and the output structure entirely unaddressed, making it incomplete for reliable 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 only 40%, so the description must compensate for the undocumented parameters. It does not explain the required 'id', the meaning of 'page', or the behavior of 'include_decided.' The 'deliberately small' comment loosely relates to per_page but adds little beyond the schema's stated default of 8.
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 conveys the resource—a small page of derivations still awaiting review—but does so as a noun phrase rather than a clear action like 'list' or 'fetch.' This makes the purpose inferable but not explicit, and it does not clearly distinguish derive_page from siblings such as derive_list or derive_features.
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 phrase 'still awaiting review' and the warning about skimmed checklists imply this tool is meant for reviewing pending derivations in small chunks. However, there is no explicit when-to-use guidance, no exclusion of alternatives, and no mention of when derive_list or derive_review would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Review backlogged features: promote to 'agreed', reassign, or drop. Rejection means two different things — 'wrong_goal' is a routing error and the feature is still wanted, so it is MOVED not dropped; 'not_wanted' is a decision about the project. A rejection REQUIRES a rationale: accumulated rationales are how the project defines what it is not, and 'no' without a reason cannot be reasoned from.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| actor | No | ||
| decisions | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden, and it goes well beyond the schema by explaining that 'wrong_goal' is a routing error that moves the feature rather than dropping it, while 'not_wanted' is a project-level decision. It also communicates why rejection rationales are mandatory. Minor gap: it only discusses two of the five rejection reasons, leaving duplicate/unclear/superseded behavior implicit.
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 with the core verb and resource front-loaded in the first clause. Every sentence earns its place: purpose, rejection semantics, and the rationale policy are all relevant and tightly written.
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?
The description gives enough for the main invocation path: agent knows what actions are available, what the two critical rejection meanings are, and why rationale is mandatory. The main gap is that duplicate/unclear/superseded are not described, but the schema enum supplies those values and the tool's most dangerous ambiguity is already resolved.
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 description adds genuine semantic value to the central 'decisions' parameter: it explains what 'accepted' effectively does, what rejection means in each key case, and why 'rationale' is required. It does not document cwd/actor, but those are largely self-expianatory from schema/names, and the core parameter is substantially clarified.
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?
States a specific verb and resource: 'Review backlogged features' with concrete outcome categories: promote to 'agreed', reassign, or drop. The operation is clear, though it does not explicitly differentiate itself from sibling tools like feature_update, so some inference is still required.
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 by 'Review backlogged features', which is enough to suggest when to call it, but there is no explicit when-not or alternative routing guidance. An agent cannot easily rule out overlaps with feature_update or feature_reassign from the description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Acknowledge a directive so it stops being returned to this worker.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| worker | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description is the sole source of behavioral information. It discloses the main effect (the directive will no longer be returned to this worker) but does not mention side effects, reversibility, or whether the directive is deleted or globally acknowledged.
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 concise, front-loaded sentence with no redundant words. It states the action and the outcome efficiently.
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?
The tool is relatively simple, but the lack of annotations, output schema, and parameter descriptions means the description carries a heavier burden. It covers the core purpose but leaves parameter semantics and behavioral details to inference.
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 schema has 33% description coverage, with only cwd described. The phrase 'this worker' gives some meaning to the worker parameter and 'acknowledge a directive' implies id refers to the directive, but id and worker remain largely undocumented in both schema and description.
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 uses a specific verb ('Acknowledge') and resource ('a directive') and adds a clear outcome ('so it stops being returned to this worker'). It is distinct from sibling tools like directive_issue and directive_poll, which serve different purposes.
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 context is clear: the tool is used when a worker wants to stop a directive from being returned. Although it does not explicitly name alternatives or exclusions, the condition is easy to infer from the wording.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Broadcast stop, pause, resume or rescan to every worker. Broadcast rather than addressed, so a worker that starts after the directive was issued still sees it — the case a point-to-point message silently misses. Scope it to a goal, or omit for all.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| kind | Yes | ||
| note | No | ||
| actor | No | ||
| scope | No | Category name, or omit for every worker. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It reveals key non-obvious behavior: directives are broadcast, persistent enough that late-starting workers still see them, and can be scoped. This goes beyond the schema. It does not cover all side effects of each directive kind, but the core behavioral trait is clearly disclosed.
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 compact and front-loaded: the core action and target appear in the first sentence, and the crucial broadcast/late-start distinction follows immediately. Every sentence adds value without redundancy.
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?
The description fully covers the central broadcast concept and scoping behavior, which are the most important non-obvious aspects. However, with no annotations, no output schema, and undocumented note/actor parameters, some operational context is missing. It is adequate but leaves room for more detail about what each directive kind actually does and how workers consume it.
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 only 40%, and the description only elaborates on 'scope'. It also names the kind values, but those are already visible in the schema enum. Parameters like 'note' and 'actor' receive no explanation in either the schema or the description, leaving significant semantic gaps that the description should compensate for.
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 ('Broadcast') and a specific resource ('stop, pause, resume or rescan to every worker'). It differentiates this tool from point-to-point/addressed messaging and from siblings like directive_poll and directive_ack by emphasizing the broadcast and late-start visibility semantics.
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 explains when to use this tool: whenever a directive must reach all workers, including those that start later. It contrasts this with point-to-point messaging and gives the scoping rule ('Scope it to a goal, or omit for all'), which is explicit usage guidance. It does not explicitly name alternative tools, but the broadcast-vs-addressed distinction provides clear direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Directives this worker has not acknowledged. Poll between units of work and obey what comes back: stop means finish the current step and stop, pause means stop and wait for resume.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| goal | No | ||
| worker | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and it does good work: it reveals that the tool returns unacknowledged directives and defines the stop and pause semantics. It doesn't cover edge cases like no pending directives or how resume is triggered, but the main runtime contract is transparent.
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 sentences with no filler. The key instruction ('poll between units of work') is front-loaded, and the response semantics are packed into a compact second sentence.
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?
The description gives enough context for the polling semantics but leaves the goal parameter unexplained and does not state what happens when there are no directives, nor how a worker is identified. For a simple read-oriented tool this is adequate but not fully 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 description coverage is only 33%; only cwd is documented. The description mentions 'this worker' but never explains the required worker parameter or what goal means, and it doesn't add parameter-level meaning to compensate for the low schema coverage.
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, 'directives this worker has not acknowledged', and gives a clear operational verb, 'Poll between units of work'. It also distinguishes this tool from directive_issue/directive_ack by focusing on unacknowledged directives rather than creating or acknowledging them.
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?
It gives explicit when-to-use guidance: poll between units of work, and instructions to obey the returned directive. It does not mention when not to poll or name alternatives, so it misses the full when/when-not contrast, but the usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What is waiting, and on what. The mirror of feature_ready.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| goal | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the burden of behavioral disclosure. It mentions the conceptual output (waiting items and blockers) but does not disclose whether the tool is read-only, how it selects results, what response shape to expect, or any dependencies or side effects.
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 extremely short and avoids wasted words. The mirror framing is an efficient orientation, though the fragment style sacrifices clarity slightly; a slightly more explicit phrasing would make it ideal.
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 no annotations and no output schema, the description leaves significant gaps: return format, filtering behavior, required context, and relationship to related tools like feature_unblocked are not addressed. For a tool with two optional parameters in a large sibling set, this is not enough context for confident 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?
The schema already describes cwd, but the goal parameter has no description. The tool description adds nothing about either parameter and does not explain how goal or cwd influence the blocked list, so it fails to compensate for the 50% schema coverage gap.
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 clearly communicates that this tool reports blocked work and the blocking dependency ('What is waiting, and on what'). 'The mirror of feature_ready' provides sibling differentiation, though it lacks an explicit verb like 'list' or 'get', so it stops just short of a top score.
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 'mirror of feature_ready' implies this tool is the inverse of feature_ready and should be chosen when the ready-view is not what is needed. However, it does not explicitly state when to use this vs. alternatives like feature_unblocked or gate tools, so usage guidance is only implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Take a feature to work on, if nobody else holds it. The claim is a LEASE with an expiry, not a flag: a worker that dies holding a flag blocks its feature forever, whereas a lease runs out and the work returns to the pool. Claim before starting, or two workers take the same item and you find out via a merge conflict.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| worker | Yes | Who is taking it — the worker or session name. | |
| lease_minutes | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It explains the lease-vs-flag model, expiry, and the consequence of not claiming. It stops short of stating failure behavior if the feature is already held or the lease duration default.
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 sentences, front-loaded with the purpose and then adding the lease model and a practical warning. The lease explanation is a bit elaborate, but it earns its place because it is central to the tool's behavior.
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?
The description gives a strong behavioral model for the claim action, which is enough to make a basic call with id and worker. However, it omits useful call context like the lease_minutes default, what happens on a conflicted claim, and what the return response contains.
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 description never mentions id, worker, cwd, or lease_minutes. Schema coverage is only 50% (id and lease_minutes lack descriptions), so the description should compensate for parameter meaning but does not.
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 and resource: 'Take a feature to work on, if nobody else holds it.' This clearly identifies a claim operation and distinguishes it from siblings like feature_propose, feature_list, and feature_release.
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?
It gives clear context for when to use the tool: claim before starting work, and only if nobody else holds the feature. It does not explicitly name alternatives or say when not to use it, so it falls just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The append-only record: what changed, when, by whom, and against which git commit. This is the audit trail that replaces git history for the tracker itself.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Omit for the whole project. | |
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It adds useful context by noting the record is append-only and serves as the audit trail replacing git history, but it does not explicitly state that the tool is read-only or describe ordering, pagination, or side-effect behavior.
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 the first precisely listing the record's key fields and the second giving useful context about its role relative to git history. Every word 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?
The description covers the essential output content and the tool's audit-trail concept, which is helpful given no output schema. However, it leaves ambiguity around limit semantics, explicit read-only behavior, and selection among sibling history-like tools, so it is adequate but not 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?
The schema already documents id and cwd well, but limit is described only by its schema constraint; the description adds nothing about parameter meaning. At 67% schema coverage, the description should compensate for the undocumented limit parameter, and it does not.
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 the append-only record and enumerates its content: what changed, when, by whom, and against which git commit. This makes it clear that the tool exposes the audit trail, though it lacks an explicit verb like 'get' or 'list'.
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?
No guidance is given on when to use feature_history versus alternatives such as feature_list or the similarly named confer_history. The description only provides background context, leaving the agent to infer the appropriate use case from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record that one feature depends on another. Priority order is meaningless without this: the highest-priority item may be blocked, and handing it to a worker wastes the worker.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The dependent feature, e.g. DIP-20 | |
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| note | No | ||
| depends_on | Yes | What it waits for, e.g. DIP-19 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'Record' and gives the rationale; it does not disclose whether the operation is idempotent, whether existing links are replaced, whether cycles are allowed, what gets changed, or what a successful response looks like. For a mutation tool, this is a significant gap.
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 first sentence is a clear, front-loaded definition. The second sentence adds motivational/usage context that helps an agent understand why the tool matters, though it is not strictly operational. Overall, it is concise and well organized.
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?
Combined with the schema, the description gives enough to identify required fields and the core action. However, with no annotations and no output schema, it omits important context such as return values, duplicate/cycle behavior, and the relationship to related tools like feature_unlink or feature_blocked.
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 schema already documents id, depends_on, and cwd with helpful examples. The description reinforces the meaning of the dependency direction and the importance of the relationship, but it adds no new parameter syntax or semantics and leaves the 'note' parameter entirely unexplained.
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 action ('Record') on a specific resource ('one feature depends on another') and clearly communicates the directed dependency relationship. The rationale about blocked high-priority items also differentiates this from sibling status tools like feature_ready or feature_blocked.
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 this tool: before relying on priority order, because dependencies can block the highest-priority item and waste a worker. It gives useful context but does not explicitly mention alternatives or exclusions, such as using feature_unlink to remove a dependency.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List tracked items, lowest priority number first. Use before proposing, to avoid duplicates.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| goal | No | ||
| kind | No | ||
| limit | No | ||
| status | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It does disclose one non-obvious behavior: results are ordered 'lowest priority number first'. However, it does not state whether the operation is read-only, what the default scope is, or what the response contains, so the behavioral disclosure is partial.
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 two short sentences and front-loads the primary purpose and ordering behavior. Every phrase earns its place, though the 'tracked itens' wording introduces slight ambiguity without adding denity.
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 list tool with no output schema and no annotations, the description is minimally viable: it names the operation, sort order, and an important usage hook. But it omits filtering semantics, default behavior, return format, and any mention of sibling history/proposal tools, leaving material gaps 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 only 20%, with only cwd documented, and the description adds no parameter-specific guidance. The prose does not explain what goal, kind, limit, or status filter or control, so with low schema coverage the description fails to compensate.
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 core action with a verb and resource: 'List tracked items', and adds concrete behavior with 'lowest priority number first'. It is clear enough to distinguish from goal_list, gate_list, and study_list, though the resource 'tracked items' is somewhat generic and could be more explicit about the underlying feature/decision inventory.
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 an explicit usage context: 'Use before proposing, to avoid duplicates.' This clearly tells the agent when to invoke the tool, but it does not mention alternatives or when not to use it, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record a feature, guardrail, schema change, risk or mitigation so it is not lost. The goal is created if it does not exist, and the id is allocated atomically by the database, so concurrent sessions cannot collide on a number. Only record what would otherwise be lost, is actionable, and is not already tracked -- check feature_list first.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| body | No | Why it is needed and what done looks like. | |
| goal | Yes | Grouping, e.g. 'DIP'. Created on first use; becomes the id prefix. | |
| kind | No | Defaults to feature. | |
| actor | No | Who proposed it: claude, chat, or user. | |
| force | No | Record even if similar items already exist. Without it, a propose that looks like a duplicate returns the candidates instead of inserting, so near-identical rows do not accumulate. | |
| title | Yes | One line, specific enough to act on. | |
| priority | No | Lower runs first. Defaults to 100. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It adds meaningful non-obvious behavior: 'The goal is created if it does not exist' and 'the id is allocated atomically... so concurrent sessions cannot collide.' This reveals side effects and concurrency guarantees beyond a simple 'create' statement. It does not mention return format or error conditions, but the atomic/allocation and goal-creation traits are substantial.
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 concise sentences with no wasted words. The core purpose is front-loaded, followed by the key concurrency/creation behavior and then a crisp usage guardrail. 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?
Given eight parameters, two required, no output schema, and a large sibling family, the description covers purpose, when-not-to-use, goal-creation side effect, and atomic id allocation. The only notable gap is that a successful propose's return value is not described, which matters more because there is no output schema.
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 already documents all eight parameters. The description adds context around goal auto-creation and id allocation, which relates to 'goal', but it does not add per-parameter meaning beyond what the schema provides. 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 opens with a clear verb and resource: 'Record a feature, guardrail, schema change, risk or mitigation', so the agent immediately knows this is a create/insert operation. It further distinguishes itself from read/tracking siblings by instructing 'check feature_list first' and by framing itself as a persistence operation.
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?
It gives explicit inclusion criteria ('what would otherwise be lost, is actionable') and an explicit exclusion ('is not already tracked -- check feature_list first'). The main gap is that it does not name a modifier sibling like feature_update as the option for already-tracked items.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What can be worked right now: not done, nothing it depends on outstanding, and no gate open on it — in goal-priority then feature-priority order. This is what a worker pulls from. Returns skipped_pending_a_gate ALONGSIDE the ready list: a gate clears only when the principal answers it, so the worker skips those and works the rest rather than stalling a whole goal on one question — but it must SAY SO out loud, because silently working around a blocked item looks exactly like having finished the goal.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| goal | No | ||
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses that the result includes skipped_pending_a_gate alongside the ready list, explains why gates cause skipping, and warns that the worker must announce the skip. It does not explicitly state whether the tool is read-only, but the behavioral caveat is unusually rich.
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 a bit long but every part contributes: ready criteria, ordering, the skipped list, and the required verbal acknowledgment. Purpose is front-loaded and the behavioral caveat 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?
The core concept, return contents, and an important behavioral expectation are covered, which is strong for a worker-facing tool. However, there is no output schema and no explanation of the goal and limit parameters, leaving material gaps for an agent that needs to invoke this tool with non-default arguments.
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?
Only cwd has a schema description, giving 33% coverage, and the description adds no parameter-level meaning at all. The goal and limit parameters are entirely unexplained in both the schema and the description, so an agent cannot infer how filtering or limiting works.
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 clearly identifies what the tool does: it returns the work that can be worked right now, with explicit readiness criteria and ordering. It is distinguishable from sibling tools like feature_list or gate_queue because it centers on the worker's pull of currently actionable items, though it never explicitly says 'returns feature records' or names an alternative.
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 says 'This is what a worker pulls from,' which gives clear intended usage context for selecting next work. It explains the skipped-gate behavior and why that matters, but it does not name alternative tools or state when not to use this one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move a feature to a different goal. The id never changes, so anything citing it in a commit message or worktree name still resolves; the move is recorded in the history with its reason. Use when a refined objective shows an item does not belong where it was filed.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| goal | Yes | The goal it should belong to. | |
| note | No | Why it does not belong where it was. | |
| actor | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the behavioral burden. It discloses two non-obvious traits: the id remains stable so external citations still resolve, and the move is recorded in history with its reason. It does not cover permissions or reversibility, but for a move operation the disclosed context is meaningful.
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 sentences with no waste: the action is front-loaded, followed by the two behavioral guarantees, then the usage trigger. Every sentence earns its place and the description is easy to scan.
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 state-changing tool with no output schema, the description covers what the move does, why the id matters, how history records it, and when to use it. It does not describe the return value or side effects on old/new goals, but those are largely implied by 'move' and are not required by the schema.
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 covers cwd, goal, and note, but leaves id and actor bare. The description adds semantics to id ('never changes') and to note ('recorded in history with its reason'), partially compensating for the 60% schema coverage. It does not explain actor, but that is a minor gap.
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?
Opens with a specific verb and resource: 'Move a feature to a different goal.' This clearly distinguishes it from siblings such as feature_propose, feature_update, feature_link, and feature_unlink by naming the intended mutation and target.
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?
Provides a concrete trigger: 'Use when a refined objective shows an item does not belong where it was filed.' It does not explicitly name exclusions or alternatives, but the stated condition is enough to route an agent to this tool rather than generic update or link actions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set acceptance criteria on many features at once. Most are derivable from the body, the code and the docs, so doing them one at a time spends a round trip per item on work that needed no decision. Anything genuinely undecidable should become a gate rather than a guess.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| actor | No | ||
| items | Yes | ||
| conferral | No | Required. ONE conferral and ONE peer call for the whole batch, not one per feature. Acceptance criteria are argued as a set — whether they are testable, whether they would let a worker call something done that is not. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden, and it does disclose the batch nature and the derivability heuristic. However, it does not say whether existing acceptance criteria are overwritten, whether a conferral is required for execution, or what happens in error or return cases, leaving important behavioral context undisclosed.
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 exactly three sentences with no fluff: the action, the rationale, and the routing rule. The most important information 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?
This is a complex batch mutation tool with a required nested conferral object and no output schema. The description provides a clear decision framework but omits side effects, overwrite semantics, and return behavior; the schema supplies the conferral contract, but the description alone is not fully sufficient for a tool of this complexity.
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 schema covers cwd and conferral well but leaves actor and items thin, with only 50% coverage overall. The description adds useful meaning for items by explaining that acceptance criteria are derivable from body/code/docs and that undecidable cases should become gates, but it does not explain actor or the non-acceptance item fields, so it only partially compensates for the coverage gap.
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 first sentence states a specific action (Set acceptance criteria) on a specific resource (many features at once), so the purpose is immediately clear. It contrasts with one-at-a-time work, but it does not explicitly name a sibling tool such as feature_update, so it does not quite reach the top distinction score.
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?
It gives an explicit positive condition for use: acceptance criteria are mostly derivable from the body, code, and docs, so batch work avoids needless round trips. It also gives an explicit negative rule: anything genuinely undecidable should become a gate rather than a guess, which routes the agent away from this tool when a decision cannot be derived.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Give up a claim, returning the feature to the pool.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| worker | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It clearly states the core side effect—the claim is given up and the feature returns to the pool—but it does not explain prerequisites, reversibility, error behavior, or effects on related data such as history or links.
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 a single, efficient sentence with no filler. It front-loads the action and outcome, and 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 three parameters, no output schema, and no annotations, this one-liner is too thin for reliable autonomous invocation. An agent gets no detail about what id and worker mean, what success or failure looks like, or what exact post-conditions hold beyond the bare outcome.
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 only 33%, covering only cwd. The description adds no direct explanation of the required id and worker parameters; it vaguely implies that id identifies the feature and worker identifies the claimant, but the required inputs remain largely undocumented.
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: 'Give up a claim, returning the feature to the pool.' It clearly communicates the operation and distinguishes feature_release from sibling tools like feature_claim and feature_reassign.
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 clear context for when to use the tool: when a worker wants to surrender a claim and make the feature available again. It does not explicitly name alternatives or exclusion conditions, but the use case is evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What a recently answered gate has released. Answering a gate changes a gate row and nothing else, so work it was holding stays invisible unless something looks — this is what a worker calls on resuming. Read each decision_note before starting: it is the answer the work was waiting on.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| since_hours | No | Default 24. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden and does meaningful work: it explains that answering a gate only changes the gate row, leaving held work invisible until looked at, and that this tool is that lookup. It also discloses that decision_note contains the awaited answer. It does not explicitly state whether the tool is read-only or describe output shape, but the 'nothing else' phrasing implies the operation is observational.
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 sentences, each earning its place: the purpose, the underlying gate-behavior context, and the operational instruction to read decision_note. It is front-loaded with the core idea and contains no filler.
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 two-parameter query tool with full schema coverage, the description is largely complete: it explains when to call it and what the returned data means. It could be more explicit about the exact output format and read-only nature, especially since there is no output schema and no annotations, but the description is still 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 schema already documents cwd and since_hours. The description adds no parameter-specific meaning, which is acceptable under the baseline for high-coverage schemas but gains no extra credit.
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 conveys that the tool reveals work released by a recently answered gate, using 'released' as the key verb and 'work' as the resource. It is clear enough for an agent to understand the tool's function, but it does not explicitly name or contrast a sibling like feature_blocked, leaving some differentiation implicit.
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: this is what a worker calls on resuming after a gate has been answered, and it instructs reading each decision_note before starting. It does not explicitly state when not to use it or name alternatives, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a dependency between two features.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| depends_on | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly implies a mutating operation but discloses no side effects, reversibility, required permissions, or what happens if the dependency does not exist, leaving significant behavioral uncertainty.
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 a single sentence with no redundant wording. It is appropriately front-loaded and communicates the primary operation clearly without wasting the agent's attention.
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 mutating tool with no annotations, no output schema, and low schema description coverage, this description is insufficient. It omits parameter roles, dependency direction, behavioral effects, and any return or error semantics, leaving important context for the agent to fill in from the tool name and parameter names.
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?
Only cwd has a schema description; id and depends_on are undocumented, and schema description coverage is only 33%. The description adds minimal parameter context by mentioning two features, but it does not clarify which parameter is the dependent feature or the dependency being removed, forcing reliance on parameter names alone.
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 action ('Remove') and a specific resource ('a dependency between two features'), clearly conveying the tool's core function. It distinguishes the tool from siblings like feature_link, which presumably creates dependencies, based on the unlink/link verb contrast.
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 explicit guidance on when to use this tool versus alternatives, nor any prerequisites or exclusion cases. While removing a dependency is implied as the use case, there is no mention of feature_link or other related tools, leaving the agent to infer selection criteria on its own.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open features with no acceptance criteria — the work list for a refine pass. Until a feature says what done looks like, 'done' is whoever-built-it's opinion.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| goal | No | ||
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry behavioral disclosure. It does communicate that only features lacking acceptance criteria are returned and frames them as refine work, but it never states whether the operation is read-only or if it has side effects.
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 sentences with the core function in the first and a rhetorical context in the second. It's concise and front-loaded, though the second sentence is not strictly necessary for invocation.
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 no annotations or output schema and two undocumented parameters, the description leaves important details unstated: what the returned list looks like, how 'goal' filters, and how 'limit' behaves. It conveys purpose but is incomplete for confident 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?
Only 1 of 3 parameters (cwd) has a schema description, and the tool description does not explain 'goal' or 'limit.' This leaves those parameters semantically opaque, and the prose adds no parameter-level meaning.
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 clear verb ('Open') and resource ('features with no acceptance criteria'), and adds the purpose as 'the work list for a refine pass.' This lets an agent distinguish it from general feature_list, though it doesn't explicitly name siblings.
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 when to use it—when preparing for a refine pass—by calling it 'the work list for a refine pass.' It does not explicitly name alternatives or conditions for not using it, so the guidance remains contextual rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change a tracked item: status, title, body or priority. Every change is recorded in the append-only history, stamped with the git commit it was made against.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | e.g. DIP-17 | |
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| body | No | ||
| note | No | Why it changed. | |
| actor | No | ||
| title | No | ||
| status | No | ||
| priority | No | ||
| acceptance | No | What done looks like, concretely enough to test. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full weight. It explicitly discloses a meaningful behavioral trait: every change is appended to an append-only history stamped with the git commit it was made against. This gives the agent valuable expectations about auditability and mutability beyond the bare 'change' verb, though it does not cover permissions or reversibility.
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 two sentences with no filler. The core action and scope are front-loaded, and the audit-history behavior is appended concisely. Every sentence contributes useful information.
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 9-parameter mutation tool with no annotations and no output schema, the description is too terse. It does not explain partial-update semantics, the intended use of actor/acceptance/note, or what the caller should expect back after invoking the tool. The schema helps, but the combination of high parameter count and lack of output schema leaves significant ambiguity.
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 44%, so the description needs to compensate for the undocumented parameters. It does add value by naming title, body, and priority as changeable fields, which the schema leaves somewhat opaque. However, it does not clarify the purpose of actor, acceptance, note, or how omitted fields behave during a partial update.
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 uses a specific verb and resource: 'Change a tracked item' and enumerates the mutable fields: status, title, body, or priority. This clearly distinguishes the tool from siblings such as feature_propose, feature_list, and feature_history, which are about creating, listing, or inspecting items rather than modifying them.
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 phrase 'tracked item' implies this is for modifying an existing item rather than proposing or listing one, but no explicit when-to-use, when-not-to-use, or alternative tool is named. It does not mention, for example, that feature_propose is the right choice for new items or feature_reassign for reassignment.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Everything needed to reason about coverage, in one read: every goal's objective, done-means, non-goals and constraints in its own words, what each holds, and every settled refusal. Read-only. This is the input to gap analysis — derive_features asks what ONE goal implies and so can only find work inside a goal somebody already wrote; this asks what the whole set fails to cover, which is the only way a MISSING goal is ever found. Returned unsummarised on purpose: a gap is noticed by reading the actual wording, and does not survive being condensed into counts.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden of behavioral disclosure. It explicitly states 'Read-only' and explains that results are returned unsummarised on purpose, with the rationale that gaps are noticed by reading actual wording and do not survive condensation into counts. It does not mention volume, size, pagination, or output envelope behavior, but the disclosed traits are meaningful and beyond trivial.
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 longer than a one-liner but every clause earns its place: it defines content, declares read-only behavior, differentiates from a sibling, and justifies unsummarised output. The core content is front-loaded with 'Everything needed to reason about coverage, in one read,' and the rest supports selection and expectations.
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 no output schema, the description does a good job explaining what will be returned and why, which covers the most important contextual gap. It also gives usage context through the derive_features contrast. It could more explicitly mention response shape or size expectations, but for a read-only scan tool the definition is largely 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?
The single parameter cwd is already fully documented in the input schema with 100% schema description coverage, so the description does not need to repeat it. The description adds no further parameter-level guidance, which is acceptable given the schema already handles the meaning. 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 clearly states what the tool does: it returns a full, unsummarised read of all goals' objectives, done-means, non-goals, constraints, holdings, and refusals for coverage reasoning. It also explicitly distinguishes itself from derive_features by contrasting whole-set coverage analysis with single-goal implication. This gives a precise verb-resource-scope identity, not just a restatement of the name.
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 explicitly says when to use this tool vs derive_features: use gap_scan to analyze what the whole set fails to cover and find MISSING goals, whereas derive_features can only find work inside goals someone already wrote. This is a clear when/alternative pairing, leaving no ambiguity about selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Approve or reject a pending gate, unblocking the session that raised it.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| note | No | ||
| decision | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It does disclose a key side effect ('unblocking the session'), but it does not mention whether the decision is reversible, what happens to the gate record, what permissions are required, or what the response contains. For a mutating tool this is a meaningful gap.
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 one succinct sentence with no filler. The core action and consequence are front-loaded, and every word contributes meaning.
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 tool with four parameters, no output schema, no annotations, and a broad sibling set, the description is too sparse. It does not explain the meaning of 'id', 'note', or 'cwd', nor does it describe return behavior or edge cases like non-pending gates. The sentence conveys intent but not enough to confidently invoke the tool in varied situations.
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 only 25%, and the description adds no parameter-level detail. It implies that 'id' identifies a pending gate and that 'decision' aligns with approve/reject, but the enum already covers that. The 'note' and 'cwd' parameters remain unexplained by both schema and description.
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 uses a specific verb ('Approve or reject') with a clear resource ('a pending gate') and states the consequence ('unblocking the session that raised it'). This clearly distinguishes it from siblings like gate_list, gate_raise, and even gate_decide_batch by focusing on a single pending gate decision.
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 context of use is implied: when a gate is pending and a session is blocked awaiting a decision. However, there is no explicit guidance about when not to use this tool or when to prefer alternatives such as gate_decide_batch, gate_reopen, or gate_reconcile.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Answer several gates at once, after a question round. Each decision applies independently and is reported separately: answering nine of eleven is a normal outcome, and one bad id must not throw away eight good answers.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| answers | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and excels: it discloses non-atomicity ("Each decision applies independently"), per-item reporting ("is reported separately"), and partial-failure acceptance ("nine of eleven is a normal outcome, one bad id must not throw away eight good answers"). This is exactly the behavioral trait an agent cannot guess from the schema.
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 sentences with the purpose front-loaded and zero redundancy with the schema: one sentence for what the tool does, two for the critical behavioral semantics. 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 moderately complex batch tool with no output schema and no annotations, the description covers the when, the what, and the failure semantics that matter most for safe invocation. The main residual gap is the return shape — "reported separately" hints at per-decision results but no response format is given.
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 50%: cwd and note are already well documented in the schema, while answers, id, and decision are not. The description compensates partially by explaining that answers are processed independently and that a bad id is tolerated, but it never defines what an id refers to in the question-round context — that gap is left to inference from sibling tools.
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?
"Answer several gates at once" states a specific verb, resource, and scope, making the batch behavior unmistakable. The framing differentiates it from the singular sibling gate_decide without needing to open either schema, and "after a question round" anchors it in the workflow.
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 its usage context — batch decisions after a question round — but never explicitly contrasts it with gate_decide for single gates or states exclusions. An agent must infer the single-vs-batch routing from the tool name and sibling list rather than from explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Decisions awaiting a human. Read-only; costs no work.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| status | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose that the operation is read-only and costs no work, which is useful safety and cost information. However, it does not describe what a decision entry looks like, whether results are paginated, what the default status is, or what happens when no decisions are awaiting a human, so behavioral transparency is only partially addressed.
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 extremely short and front-loads the core purpose and safety profile in two phrases. Every clause carries some signal: "Decisions awaiting a human" is purpose, "Read-only" is safety, "costs no work" is operational cost. While it is under-specified in other dimensions, it is not bloated or 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?
For a simple list tool with no output schema and no annotations, the description is too thin to be complete. It does not explain the status parameter's meaning or default, what fields each decision entry contains, or how this tool relates to gate_queue and other gate_* siblings. An agent could call it but would be guessing about the semantics of important inputs and outputs.
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 only 50%: the cwd parameter is documented in the schema, but the status parameter is only given an enum without explanation. The tool description does not compensate by explaining status semantics or defaults. An agent cannot confidently know whether omitting status returns pending decisions, all decisions, or something else.
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 identifies the resource as decisions awaiting a human and marks the operation as read-only, so an agent can infer this is a list operation. However, it never explicitly states a verb like 'list' or 'show', and it does not distinguish itself from similar list-like siblings such as gate_queue or gate_list variants. The phrase 'Decisions awaiting a human' is helpful but does not fully clarify what the tool returns or how it relates to the other gate_* tools.
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 no explicit guidance on when to use this tool versus alternatives like gate_queue, gate_reconcile, or gate_raise. The comment 'Read-only; costs no work' implies it is a safe, cheap operation, but it does not state when a user should choose gate_list over other decision-related tools. Without exclusions or alternative routing, an agent has limited basis for selecting this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every pending decision, oldest first, shaped to be answered in one sitting rather than as interruptions. Carries age, what each gate blocks, the options and the raiser's recommendation — a gate that only asks is a gate that gets deferred. Use this for the periodic question round; it records that each gate was put to the principal.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| goal | No | Limit to one goal's gates. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden and does disclose a key side effect: calling this tool records that each gate was put to the principal. It also reveals ordering and the design intent to batch decisions into one sitting, though it leaves details like error behavior and repeated-call effects unstated.
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 compact and front-loads the core behavior before adding context. The aphorism 'a gate that only asks is a gate that gets deferred' adds flavor and rationale, but it is the least directly actionable sentence, keeping this from a perfect score.
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?
The description compensates for the lack of an output schema by specifying what each queue item carries and noting the audit side effect. It does not mention pagination or parameter-specific behaviors, but both parameters are already well documented in the schema.
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 schema already documents both parameters completely, so the description does not need to carry much parameter burden. It adds no extra meaning for cwd or goal beyond what the schema provides, matching the baseline for 100% schema coverage.
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 clearly identifies the tool as a queue of every pending decision, ordered oldest first, and specifies the fields it carries: age, what each gate blocks, options, and the raiser's recommendation. It distinguishes itself from siblings by tying it to the periodic question round and the recording of gates being put to the principal.
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 an explicit use case—'Use this for the periodic question round'—and explains the recording behavior. It does not name alternative tools or state when not to use it, but the intended context is clear enough for an agent to select it over a general list or decision tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Raise a decision the working session must not take alone: an architectural choice, an install, a spend, or anything irreversible. The session should stop and wait -- this is how 'this costs $40, are you good with that' becomes a queued question rather than a message someone had to be present to catch.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| goal | No | Which goal this blocks. | |
| kind | Yes | ||
| actor | No | ||
| blocks | No | Feature ids stalled by this. Age plus what it blocks is what makes a gate urgent. | |
| context | No | What it unblocks, and what happens either way. | |
| options | No | The alternatives, stated so they can be chosen between. | |
| cost_usd | No | For spend gates. | |
| question | Yes | The decision, asked so it can be answered yes or no. | |
| conferral | No | Required for soft gates (architectural, install): they are forks two specialists settle, so raising one without having conferred is refused. A converged conferral closes the gate without troubling the principal; a stalemate or regression promotes it to them with both positions attached. spend and irreversible gates are always the principal's and this is optional on them. | |
| recommendation | No | What you would do, and why. A gate that only asks gets deferred; one that recommends can be answered in seconds. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description has to carry behavioral weight, and it does convey queued, asynchronous behavior ('queued question rather than a message someone had to be present to catch') and a blocking wait. However, it overgeneralizes by implying every raise waits on a principal, while the schema says a converged conferral can close a soft gate without troubling the principal.
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 sentences, with the purpose statement front-loaded and a concrete example earning the second sentence. There is no filler or redundant restating of the tool name.
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?
The tool is complex (11 parameters, a nested conferral object, no output schema, no annotations), and the description alone leaves important operational detail implicit, such as the conferral requirement for soft gates. The schema compensates with rich field-level descriptions, so description plus schema is workable, but the high-level text is not fully complete on its own.
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 82%, so the schema already documents most parameters in detail; the description only adds semantic color to 'kind' by giving examples such as a $40 spend. That matches the baseline 3: the description does not need to re-list parameters but also does not materially deepen their meaning.
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 specifies a concrete action ('raise') and a clear target: decisions the working session must not take alone, with four explicit trigger categories (architectural choice, install, spend, irreversible). It does not explicitly contrast itself with sibling gate tools such as gate_decide or gate_queue, so it stops short of a 5.
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, actionable conditions for use: any architectural, install, spend, or irreversible decision, and it says the session should stop and wait. It does not spell out when not to raise (for example, after a converged conferral) or name an alternative tool, but the trigger context is clear rather than merely implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Re-check a pending gate against the tree as it is now. A gate freezes its question at the moment it was raised and nothing re-reads it, so work that lands afterwards can answer it, invalidate its premise, or build the very thing it asks whether to build -- and it goes on being asked, because the row still says pending. Run this over every pending gate before putting any of them to the principal. 'moot' closes it as settled (never as a decision they did not take, and reversible with gate_reopen); 'repose' rewrites the question and resets asked_count. Both require evidence naming a path or a commit.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| context | No | ||
| options | No | repose: the options as they now stand. | |
| verdict | Yes | moot: the tree answers it. repose: still a decision, but the premise moved. | |
| evidence | Yes | What you read that settles or changes it -- paths, or a commit. Not 'I checked'. | |
| question | No | repose: the new question, against the tree as it is. | |
| recommendation | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so richly. It explains the freezing behavior of gates, that 'moot' closes without counting as a decision and is reversible via gate_reopen, that 'repose' rewrites the question and resets asked_count, and that both verdicts require evidence naming a path or commit. This goes well beyond the schema.
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 front-loaded with the action, then gives the rationale, the timing, and the verdict semantics in a compact sequence. Every sentence earns its place, and there is no filler or repetition of schema field names.
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?
The description is largely complete for a complex tool with no output schema: it covers purpose, when to use it, what each verdict does, reversibility, evidence requirements, and side effects. It does not describe the return/response shape or the context/recommendation parameters, but those are minor for an agent correctly invoking the tool.
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 63%, leaving several parameters undocumented, but the description adds meaningful semantics to the verdict enum and evidence requirement: 'moot' is never a decision the principal did not take, and 'repose' resets asked_count. It does not individually explain context or recommendation, but the conceptual grounding it provides is valuable.
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 and resource: 'Re-check a pending gate against the tree as it is now.' It clearly distinguishes gate_reconcile from sibling tools like gate_raise, gate_decide, and gate_reopen by explaining that it addresses stale pending gates whose frozen questions may have been answered or invalidated by later work.
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 an explicit usage directive: 'Run this over every pending gate before putting any of them to the principal.' It also references gate_reopen for reversibility. It does not explicitly state when not to use it versus all alternatives, but the context is strong enough for an agent to know when it applies.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pull back a gate the pair settled. Auto-settling is only safe because it is reversible: two models can be confidently wrong together, and the principal finding that out later needs a lever, not an argument. Reopened gates come back as hard.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| note | No | Why it is being reopened. Outlives the decision. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral disclosure burden. It discloses that reopened gates 'come back as hard' and frames the operation as a reversible lever, adding meaningful context beyond the schema. However, it does not state effects on related gates, whether reopening can fail, or what happens if the gate is already open.
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 sentences and about 45 words, with the core action front-loaded in the first sentence. The middle sentence is somewhat philosophical but it earns its place by explaining why the operation exists; there is no filler beyond that.
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 3-parameter mutation, the description gives the key behavioral fact and rationale, while the schema covers cwd and note. It is incomplete on id semantics and postconditions, and without an output schema an agent gets no guidance on what a successful reopen returns.
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 only 67%, and the required 'id' parameter lacks a description that tells the agent which gate it refers to. The prose adds no parameter-level detail; it never mentions id, cwd, or note. With coverage below the high threshold and no compensation in the description, a 2 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 first sentence, 'Pull back a gate the pair settled,' gives a specific verb and resource and clearly identifies this as the undo counterpart to gate settling. It is not tautological and it differentiates the tool from gate_raise/gate_decide. The phrase 'the pair settled' is somewhat jargon-heavy, so it is not a 5.
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 conveys the intended situation: reopen when an auto-settled gate is later found wrong, because auto-settling is only safe due to reversibility. It stops short of naming alternative tools or stating when not to use it, but the use case is clearly implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a goal that does not exist yet, at the END of a definition session. The name comes out of the conversation rather than going into it — nobody should have to invent an identifier before working out what the thing is. Follow immediately with goal_refine to record its objective. Check goal_list first: a near-duplicate goal fragments the queue.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| name | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the burden of behavioral disclosure. It discloses that this creates a new goal, warns that near-duplicates fragment the queue, and explains the conversational source of the name. It does not mention return values or duplicate-handling behavior, but for a simple create operation the stated behavior is substantial and useful.
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 sentences, with the core purpose front-loaded in the first clause. Every sentence carries operational value: timing, naming philosophy, prerequisite, and next step. There is no filler or repetition of schema details.
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 two-parameter tool with no output schema, the description provides enough context to call it correctly: when to call it, what name semantics to follow, what to check first, and what to do immediately after. Nothing essential for selecting or invoking the tool is missing.
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 50%: cwd is well documented in the schema, but name has no schema description. The description compensates for name by explaining its conceptual origin — it comes out of the conversation, not user invention. This adds meaningful semantics beyond the bare string field.
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 opens with a specific verb and resource: 'Create a goal', then adds distinctive constraints: 'that does not exist yet' and 'at the END of a definition session'. It also differentiates from nearby goal tools by explaining that the name emerges from conversation rather than being supplied up front, which separates it from goal_set and goal_refine.
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 when-to-use guidance: only at the end of a definition session, and only for goals that do not yet exist. It prescribes a prerequisite ('Check goal_list first') and a mandatory follow-up ('Follow immediately with goal_refine'), making the intended workflow unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Categories with their priority, parallelism cap, and item counts. Every feature must belong to one — an uncategorised item is one nobody picks up. Check here before proposing, so a near-duplicate goal is not created alongside an existing one.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It conveys that the tool returns category metadata and is meant for inspection before proposing, but it does not explicitly state it is read-only, how cwd affects results, or how the list is ordered/grouped.
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 short sentences, each with a clear role: content, domain importance, and actionable usage. There is no filler or redundant wording.
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 listing tool with one optional parameter and no output schema, the description covers the returned attributes and the reason to call it. It could be slightly more explicit that the tool is read-only and returns a list, but nothing essential is missing for correct selection and 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?
The only parameter, cwd, is already fully documented in the schema, so schema coverage is 100%. The description adds no parameter-specific detail, matching the baseline for full schema coverage.
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 identifies the resource (categories/goals) and the returned attributes (priority, parallelism cap, item counts), and implies a listing action. It is distinguishable from feature_list and goal_show because it emphasizes categories and the pre-proposal check, though it never explicitly states a verb like 'list'.
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?
It gives a concrete usage instruction: check this tool before proposing a feature so near-duplicate goals are not created. This is clear context, but it does not name alternative tools or state explicit when-not-to-use conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Everything filed under a goal, for re-testing membership once its objective is agreed. Imported features inherited their goal from which document heading they sat under — a filing location, not a judgement that the item serves the objective, because at import time there was no objective to test against. Run this after refining a goal that already holds work.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| name | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses a non-obvious behavior: imported features inherit goal membership from document headings, so membership reflects filing location rather than objective alignment. However, with no annotations provided, it does not explicitly state whether this is read-only or what the output shape will be.
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 front-loaded with the core purpose and stays reasonably concise. The middle sentence supplies useful background about import-time inheritance, though it is slightly longer than necessary for the core instruction.
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?
The description provides strong context about why membership may be stale and when to invoke the tool. However, with no output schema and sparse parameter details in the description, an agent still lacks complete guidance on what response to expect and how to format the goal identifier.
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 only 50%, and the description does not compensate. It implies the 'name' parameter refers to a goal, but it does not clarify the expected format, how the goal is identified, or what 'cwd' contributes beyond the schema's existing description.
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 clearly identifies the tool's scope as everything filed under a goal, and explains its purpose is re-testing membership against an agreed objective. It distinguishes the concept from merely listing features by describing the filing-location origin, though it uses a noun phrase rather than an explicit verb like 'list'.
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 an explicit usage instruction: 'Run this after refining a goal that already holds work.' This provides clear context for when the tool is appropriate, though it does not mention alternatives or explicitly say when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List categories holding no features, and optionally remove them. Defaults to a dry run: a goal with work is never removed, and Miscellaneous is always kept.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| apply | No | Omit for a dry run. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral burden. It discloses the dry-run default, the protected status of goals with work, and that Miscellaneous is always kept. This meaningfully informs the agent about side effects and safety guardrails.
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 two sentences: the first states the primary action, and the second adds the essential safety conditions. There is no fluff or repetition, and the most important behavioral information is front-loaded.
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 tool with only two optional parameters and no required inputs, the description covers the core behavior and safety constraints well. It does not specify the exact output format, but since there is no output schema and the action says 'List categories,' this is a minor gap rather than a functional one.
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 parameters are already documented. The description adds important semantics around the apply parameter: omitting it results in a dry run, and even when applying, certain goals are never removed. This goes beyond the schema's 'Omit for a dry run.'
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 action: list categories with no features and optionally remove them, which clearly distinguishes it from goal_list or feature_list. The term 'categories' is slightly ambiguous but is clarified by 'goal with work' in the next sentence, meaning goal categories.
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?
It gives clear context for when to use the tool: identifying empty goal categories and optionally removing them. However, it does not explicitly state when not to use it or point to alternatives like goal_list or goal_show for inspecting goals in more detail.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record a goal's objective after a refinement session with the principal. A goal carrying only a name and a priority is a filing label: nothing in it says what is being attempted, so a worker cannot judge whether a feature actually serves it. Do NOT call this mid-discussion — record once, when consensus is reached.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| name | Yes | ||
| actor | No | ||
| status | No | ||
| doc_ref | No | Where the objective was lifted from — file plus heading, e.g. "docs/feature_tracking.md#go-live-gates-glg". Record it even when the document was thin, so a later reader can tell a lifted objective from an invented one, and so the next pass reads one section instead of re-grepping the whole file. | |
| priority | No | Lower is worked first. | |
| non_goals | No | What is deliberately excluded. The part people skip and the part that matters: goal drift is rarely someone pursuing the wrong objective, it is someone pursuing a defensible neighbouring one. | |
| objective | No | What is actually being achieved, in the principal's terms, not the code's. | |
| rationale | No | Why it matters, and what happens if it is not done. | |
| done_means | No | How anyone can tell the goal is finished rather than merely worked on. | |
| constraints | No | What must hold — budget, latency, compatibility. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It implies a persistent write that should occur exactly once and explains the state it addresses, but it does not state whether an existing objective is overwritten, whether the goal must already exist, or what response the agent should expect. Those gaps keep it below a 4.
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 purposeful sentences: one for the action, one for the rationale, and one for the timing rule. It is front-loaded with the core directive and contains no filler.
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 write tool with no annotations and no output schema, the description plus the rich parameter schema is mostly sufficient. An agent understands what to do, when to do it, and what the core fields mean. It falls just short of fully complete because required-name semantics, overwrite behavior, and return behavior remain implicit.
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 73%, and most parameters already carry detailed descriptions in the schema itself. The narrative adds conceptual value about objective versus name/priority, but it does not clarify undocumented parameters such as `name` and `actor`, nor does it compensate for all gaps across the 11-parameter surface.
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 opening sentence names a specific action and resource: record a goal's objective after a refinement session. The filing-label explanation further clarifies why this is needed and distinguishes it from merely listing or naming goals, so an agent can recognize the intended operation.
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 a clear trigger ('after a refinement session with the principal') and a clear prohibition ('Do NOT call this mid-discussion — record once, when consensus is reached'). It directly addresses the timing risk for this tool, which is strong practical routing even without naming a sibling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Refine several goals in one call. Drafting is derivable from each goal's own documentation, so the expensive part is the handful of genuine decisions, not a sitting per goal. Read the source document ONCE and slice it by heading — re-reading it per goal is the same file four times. Draft the lot, record the lot with doc_ref so the next pass has a pointer instead of a search, and raise the questions that remain as gates.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| actor | No | ||
| goals | Yes | ||
| conferral | No | Required. ONE conferral and ONE peer call for the whole batch — not one per goal, which multiplies the wall clock by the batch size and asks a worse question each time. The pair argues about the SET of objectives — whether they overlap, whether one swallows another — and that argument does not decompose into one review per goal. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden, and it delivers: it states the tool will read the source document once, slice it by heading, draft all goals, record doc_refs for future passes, and raise unresolved questions as gates. This goes well beyond a generic 'refine' and discloses real side effects and workflow traits. It does not cover reversibility or return values, but for a drafting/refinement tool this is substantive disclosure.
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 appropriately sized and front-loaded with the core purpose. The middle sentence about the 'expensive part' and 'not a sitting per goal' is somewhat rhetorical but still earns its place by justifying the batching pattern. Overall, every sentence adds either instruction or context without excessive bloat.
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?
The schema descriptions, especially for conferral, are rich and fill many gaps. However, the top-level schema marks only goals as required while the conferral description insists it is required—an internal inconsistency the agent must resolve. The main description also leaves the source document unparameterized, and there is no output schema, so return behavior is completely unspecified.
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 50%, with actor having no description at all. The main description adds useful semantics for doc_ref—'a pointer instead of a search'—and for the batch behavior of the goals array. However, it does not clarify cwd, actor, or how the 'source document' mentioned in the description maps to any actual parameter, leaving some semantic gaps.
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 opening sentence 'Refine several goals in one call' is a specific verb+resource statement, and it clearly distinguishes this from the sibling goal_refine by emphasizing the batch nature. The rest of the description reinforces the purpose by outlining the workflow: read once, slice by heading, draft all, record doc_refs, and raise remaining questions as gates.
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 clear context for when to use the tool—when several goals need refinement and the source document can be read once—and it explains the efficiency rationale. It does not explicitly name goal_refine as the single-goal alternative or list exclusions, but the batching guidance is strong enough to route an agent appropriately. The conferral parameter description adds the key guideline of one peer call per batch.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set a goal's priority and how many of its features may be worked at once. Parallelism is capped per goal rather than by token budget: the limit that matters is how many things are changing simultaneously.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| name | Yes | ||
| priority | No | Lower is worked first. | |
| max_parallel | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral burden. It does add a meaningful behavioral clarification: parallelism is capped per goal rather than by token budget, and the limiting factor is simultaneous changes. However, it does not disclose effects like whether existing settings are overwritten, permission requirements, or reversibility, which would be useful for a mutation tool.
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 two sentences with no filler. The primary action is front-loaded, and the second sentence earns its place by clarifying a subtle point about parallelism. It is appropriately concise.
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?
This is a mutation-like tool with no annotations and no output schema, so the description needs to convey more context. It explains the max_parallel concept but does not mention return behavior, error conditions, what happens to existing values, or any necessary prerequisites. For a tool with four parameters, including one undocumented name parameter, the description is not complete enough.
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 50%, so the description needs to add some meaning beyond the schema. It does clarify max_parallel by explaining the per-goal parallelism model, which is not in the schema. However, it does not add meaning for 'name' or cwd, and priority already has a schema description ('Lower is worked first'). The description helps but only partially compensates for the coverage gap.
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 clear operation ('Set') on a specific resource ('a goal's priority and how many of its features may be worked at once'). This is precise enough to separate it from goal_list, goal_show, goal_refine, and other goal-related siblings. It does not name an alternative, but the operation is distinct and unambiguous.
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?
There is no explicit guidance about when to use this tool or when to prefer an alternative. The second sentence explains a semantic detail about parallelism rather than providing usage conditions, prerequisites, or exclusions. An agent must infer when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One goal in full — objective, what done means, what is explicitly excluded, constraints — with its item counts. A worker should read this before starting, so it can tell whether what it is about to build actually serves the goal.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| name | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description carries the full burden. It discloses exactly what the operation returns and frames the tool as a read action by saying the worker 'should read this', implying no side effects. It does not discuss errors or auth, but for a simple show operation this is adequate.
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 tight sentences with no filler. The first sentence front-loads the output content; the second provides the usage directive. 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 single-goal retrieval tool, this description covers the return content and the when-to-use guidance, and the schema covers cwd. It does not explain not-found behavior or output format, but those are minor gaps given the simplicity of the tool.
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 only 50%: the cwd parameter is documented but the required name parameter is not. The description never mentions either parameter, so it does not compensate for the gap. The agent must infer that 'name' selects the goal to show.
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 clearly states what the tool returns: one full goal with objective, definition of done, exclusions, constraints, and item counts. It lacks an explicit verb like 'retrieve' or 'display', but the phrase 'One goal in full' plus the tool name make the purpose clear and distinguish it from a goal list.
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?
It explicitly tells the worker when to call this tool: before starting work, so it can verify that what it builds serves the goal. It does not mention alternative tools or when not to use it, so it misses the top score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Goals with no objective or no definition of done, ordered by how much work they already hold. These cannot be reasoned about: work under them is being ordered without anything saying what it is for. Refine the ones holding the most first. Each row carries its doc_ref where one is known, so the refine pass reads that section rather than searching the tracker markdown for it once per goal.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the behavioral burden. It discloses filtering criteria, ordering by work held, and the row-level doc_ref behavior. It implies a read-only report but does not explicitly state side-effect absence or pagination limits.
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 sentences, all contributing either selection criteria, rationale, or workflow guidance. The first sentence front-loads the core purpose. Slightly wordy, but each 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?
With no output schema, the description explains that rows carry doc_ref where known, which is enough to support the refine workflow. It does not enumerate all return fields, but for a simple filtered list tool with one optional parameter, the coverage is adequate.
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 only parameter, cwd, is fully documented in the schema with 100% coverage. The description does not add anything about how cwd affects the result, so the 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 clearly identifies the tool as a listing of goals lacking an objective or definition of done, ordered by carried work. It is distinct from generic goal_list and goal_show tools, but it does not use an explicit verb like 'list' or 'get'.
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 actionable guidance: refine the goals holding the most work first, and use the doc_ref to avoid searching the tracker. It implies a workflow but does not explicitly name the refine tool or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Wind the project down and leave it resumable. Broadcasts stop, then stashes every uncommitted change in every worktree — untracked files included — and records where, tying each stash to the feature it belongs to. Does NOT wait for workers: waiting on one that may not poll again turns a wind-down into a vigil, and anything written afterwards is caught by the next run. Use force:true to also release every open claim, which is the 'kill it' form — deliberate, because releasing a live worker's claim invites two workers onto one feature.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| note | No | Why, recorded on the directive. | |
| actor | No | ||
| force | No | Also release every open claim. For when processes are being killed rather than asked to stop. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full disclosure burden and does so excellently. It reveals operation ordering, broad stash scope including untracked files, non-blocking behavior, and the specific hazard of force releasing a live worker's claim.
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 sentences deliver purpose, mechanism, a stated non-wait rationale, and force guidance without redundancy. Every clause adds information, and the most important safety caveat is placed at the end where it gets focused emphasis.
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 side-effect-heavy shutdown with no output schema and no annotations, the description covers the main workflow, side effects, ordering, and risks well. It stops short of full completeness by not describing the return/confirmation format or explicitly pointing to stash_restore as the resumption path.
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 75%, which establishes a baseline of 3. The description adds real value by expanding force beyond its schema text into a deliberate kill-it action with a concrete risk, and by tying cwd to worktree behavior. actor remains undocumented in both, but its meaning is conventional enough not to be a critical gap.
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 ('Wind the project down') and expands into concrete actions: broadcast stop, stash all uncommitted changes in every worktree, and record where each stash lives. This uniquely identifies oz_shutdown among siblings and also explains what 'shutdown' means in this system.
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?
It gives explicit context on when to use force:true, calling it the deliberate 'kill it' form, and explains why the tool deliberately does not wait for workers. It does not name alternative sibling tools for partial or per-feature shutdown, so it falls just short of fully explicit routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Coverage by dimension: how many features are unknown, missing, partial or satisfied. The cheap probe's target list — it decides where to spend effort, and is not itself the fix.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| goal | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It states that the tool is a probe, reports coverage states, and explicitly says it is not the fix, implying non-mutating behavior. However, it does not clarify whether it requires a prior scan, how fresh the data is, or what 'cheap' means operationally.
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 concise, two sentences, with the core output stated first and the strategic purpose second. The phrasing 'cheap probe's target list' is somewhat cryptic but does not waste words. It earns high marks for brevity and front-loading.
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?
The description gives a rough idea of the return value—counts per state—but leaves key context undefined: what dimensions are, how the `goal` parameter factors in, and how this tool relates to parity_scan or gap_scan. With no output schema and no annotations, these omissions make the tool hard to invoke with confidence.
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 50%, with `cwd` documented but `goal` entirely undescribed. The description adds no parameter meaning and fails to clarify what `goal` represents in the context of coverage gaps. This is a notable gap for an agent trying to invoke the tool correctly.
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 identifies the tool's output as coverage by dimension with counts of unknown, missing, partial, or satisfied features. It also frames it as a cheap probe's target list, which conveys its role as a diagnostic. However, it lacks an explicit verb and does not differentiate it from sibling tools like parity_scan or gap_scan.
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 usage context: it is a cheap probe that decides where to spend effort and is not itself the fix. This gives a clear sense of when to consult it, but it does not explicitly mention alternatives, prerequisites, or when not to use it. The guidance is embedded rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run the cheap probe for one dimension across every feature and record the result. parity_gaps only reads; this is what makes the states real. A probe decides where to spend effort and is not itself the fix, so it is deliberately narrow: it records what was checked in each row's detail, because 'the id is not mentioned' must never be mistaken for 'the work is not done'. Probes exist for documentation and code; the others need a real check — a build, an applied migration — rather than a reference search.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| actor | No | ||
| dimension | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose that the tool records a result and writes state, unlike parity_gaps, and it emphasizes that the probe is deliberately narrow and not a fix. It also clarifies the recording granularity: what was checked is recorded in each row's detail, which prevents mistaking absence of mention for absence of work.
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 first sentence is front-loaded and useful, but the third and fourth sentences become philosophical and repetive, re-stating that the probe is narrow and records what checked. The description earns its place overall, but it could be tightened significantly without losing meaning.
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?
The tool has no annotations and no output schema, so the description must provide context. It covers the main purpose, a key sibling contrast, and the recording behavior, but it does not state what the return value is, what 'the states' are exactly, or what side effects beyond recording occur. For a tool that appears to write parity state, this is a meaningful gap, though not severe enough to make invocation impossible.
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?
Only one of three parameters (cwd) has schema description, so coverage is low and the description needs to compensate. The description does add meaning to the dimension by saying probes exist for documentation and code and that other dimensions require real checks, which aligns with the dimension enum. However, neither the actor parameter nor the dimension parameter is explained explicitly in the description beyond that indirect reference, and cwd receives no description-level elaboration beyond its schema text.
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 action: run the cheap probe for one dimension across every feature and record the result. It also differentiates from parity_gaps, which is said to only read, making it clearer what parity_scan does that its sibling does not. The phrase 'makes the states real' is somewhat abstract, but the core function and scope are identifiable.
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 explicitly contrast parity_scan with parity_gaps ('parity_gaps only reads; this is what makes the states real'), giving an agent a basis for choosing between them. It also explains that cheap probes are only appropriate for documentation and code, while other dimensions need a real check such as a build or applied migration, effectively stating when not to use this reference-search-like tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record whether a feature is covered in one dimension — code, unit tests, functional tests, documentation, builds, infrastructure. Work is only done when it is done in every dimension; tracking code alone lets the rest drift silently.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| actor | No | ||
| state | Yes | ||
| detail | No | What was checked, and how. | |
| dimension | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden of disclosing mutation, overwrite semantics, idempotency, and side effects. It only says 'Record...' and does not state whether this updates existing values, whether the feature id must already exist, or whether history is written. This is too thin for a write tool.
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 sentences, with the action front-loaded and the reasoning attached succinctly attached. The second sentence earns its place by motivating why every dimension should be tracked rather than just code.
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 mutation tool with six parameters, no annotations, and no output schema, this description is incomplete. id is undefined, state semantics are absent, and the relationship to feature_* and parity_* siblings is only implicit. An agent could guess the intent but cannot confidently invoke it correctly for all enum values and edge cases.
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 only 33%, so the description needs to explain id, state, dimension, and actor, but it does not. It lists some dimension values but omits 'screens' and 'features' from the enum and never explains the meaning of state values like 'missing', 'partial', or 'satisfied'. It adds domain context but not the parameter-level semantics an agent needs.
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 uses a specific verb ('Record') and a clear resource: a feature's coverage in a single dimension, with examples. 'One dimension' helps set it apart from the query-oriented parity_gaps and parity_scan siblings. Minor omission of 'screens' and 'features' from the dimension list does not obscure the core purpose.
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 second sentence gives real usage guidance: record every dimension because work is only done when all dimensions are done, and warn against tracking only code. It does not explicitly name alternatives or exclusions, but the context for when to record each dimension is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What this project is NOT: goals' stated non-goals, plus every refusal with its reasoning. The accumulated negative definition — boundaries nobody wrote into a goal statement but which were decided one refusal at a time. Read before deriving or proposing anything.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| goal | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that the tool exposes an 'accumulated negative definition' built from refusals, and the imperative 'Read' implies a non-mutating operation. However, it does not state the output shape, whether any side effects occur, or prerequisites. It adds useful conceptual context but not full behavioral transparency.
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 short sentences, each earning its place: the first states the core definition, the second elaborates on the source of boundaries, and the third gives a direct usage instruction. No fluff, front-loaded, and memorable.
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?
The description conveys purpose and when to use, but with no output schema and no parameter semantics for 'goal', it is not fully complete. An agent knows to read it before deriving/proposing, but not what the result will look like or how the 'goal' parameter affects the result. Given the simple optional-parameter surface, it is adequate but has clear gaps.
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 only 50%; the 'goal' parameter has no description in the schema, and the tool description does not compensate. The description does not mention 'cwd' or 'goal' at all, so an agent is left to infer what 'goal' filters or specifies. This is a significant gap given the half-documented 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 clearly identifies the tool as a resource about what the project is NOT — non-goals, refusals, and their reasoning. This distinguishes it from siblings like derive_features or feature_propose. However, it lacks an explicit verb like 'retrieve' or 'list'; 'Read before...' implies the action but does not name it directly.
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 phrase 'Read before deriving or proposing anything' gives explicit context for when to use this tool — as a prerequisite for derivation or proposal workflows. It does not name alternatives or exclusions, but the instruction is clear enough for an agent to know this should be consulted early.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cross-track state in one call: counts, blocked, pending gates, worker liveness, and every worktree's uncommitted work. Reads working trees, not just commits — measured on this project, every worktree reported zero commits ahead while two held real uncommitted work, so a standup built on git history alone calls active tracks idle.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral burden. It meaningfully discloses that this tool reads working trees, not just commit history, and explains why that matters with a concrete warning about worktree divergence. It does not mention absence of side effects or performance considerations, but nothing in the description suggests mutation and the read-only tone is consistent.
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 two sentences and efficiently front-loads the core value proposition. The second sentence uses an anecdote to justify the working-tree read behavior, which is useful albeit slightly verbose; it still earns its place by alerting the agent to a subtle correctness pitfall.
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?
The tool has only one optional, schema-documented parameter, and the description enumerates the key output dimensions even though no output schema exists. It doesn't detail return formatting or exact field names, but for a cross-track status snapshot the described scope is sufficient for a capable agent 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 description coverage is 100%, and the single 'cwd' parameter is already well documented in the schema. The tool description does not add parameter-level detail, but because the schema fully covers it, the baseline rating 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 names a concrete deliverable: cross-track state in one call, and enumerates exactly what it surfaces: counts, blocked items, pending gates, worker liveness, and uncommitted worktree changes. It clearly differentiates from sibling tools like feature_list, gate_list, and worker_list by being an aggregate cross-track snapshot rather than a single-track 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?
It establishes clear usage context: use this when you want cross-track state in a single call. It does not explicitly name alternatives or exclusion conditions, but the description's emphasis on reading working trees and covering multiple tracks gives an agent enough context to choose it over narrower sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Work interrupted by a shutdown and not yet restored, newest first. Each names the worktree it came from — a stash only applies in the tree it was taken in.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| include_restored | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It discloses that results are newest first, that each entry names its originating worktree, and that a stash only applies in the tree it was taken from. These are meaningful behavioral details beyond the name and schema. It does not mention output format or side effects, but the read-only nature is reasonably clear from 'list'.
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 sentences with no filler. The primary purpose and ordering are front-loaded, and the important worktree caveat is placed second. Every sentence contributes useful information.
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?
The description adequately explains the core purpose and an important behavioral constraint, but it leaves include_restored unexplained, and there is no output schema to clarify the return shape. For a simple listing tool this is close to adequate, but the missing parameter semantics prevent it from being fully 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 description coverage is only 50%, and the description does not compensate for the undocumented include_restored parameter. The cwd parameter is described in the schema and echoed by the worktree context phrase, but include_restored's meaning and effect are left entirely to inference. Since the description adds no parameter-level guidance beyond what the schema already says for one parameter, this is a clear gap.
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 clearly identifies the resource as work interrupted by a shutdown and not yet restored, and specifies that results are ordered newest first. It strongly implies a list operation even though it does not begin with an explicit verb, and it distinguishes this from stash_restore by focusing on listing, not restoring.
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 useful context for when to use the tool: when you need to see shutdown-interrupted work that has not yet been restored. It does not explicitly name stash_restore as the alternative, but the 'not yet restored' framing and sibling tool list make the intended usage clear. No exclusion or conditional guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Put interrupted work back. Applied by sha rather than by position, and the stash entry is applied rather than dropped — so a restore that conflicts can be retried or abandoned without the work having evaporated. Refuses if the target worktree is already dirty: stacking a stash on top mixes two sets of half-finished work with no way to separate them afterwards.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure, and it does so excellently. It explains that the stash is applied rather than dropped, that conflicts can be retried or abandoned without losing work, and that dirty worktrees are rejected with a clear rationale. This is far beyond what the schema alone provides.
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 purposeful sentences with no wasted words. The core action is front-loaded, and the behavioral and safety details are presented efficiently with a clear rationale. 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?
Given the lack of annotations and output schema, the description is nearly complete: it covers the operation, non-destructive behavior, conflict handling, and dirty-worktree refusal. The main gap is explicit documentation of the required id parameter—how it should be obtained and formatted—so an agent might still be uncertain about the exact value to pass.
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 id parameter has no schema description, and the description only indirectly addresses it by saying the stash entry is 'applied by sha rather than by position.' This adds useful meaning but does not explicitly map 'sha' to the integer id parameter, and the wording is potentially confusing given id's integer type. The cwd parameter is already well described 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 clearly identifies the action ('Put interrupted work back'), the resource ('stash entry'), and the key distinguishing mechanism ('applied by sha rather than by position'). It is readily distinguishable from the only sibling tool, stash_list, because it describes restoration rather than 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 provides clear context for when to use the tool: restoring stashed work back into a worktree. It also gives an explicit refusal condition ('Refuses if the target worktree is already dirty') and explains why. However, it does not name alternatives, such as stash_list for finding the relevant id, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record a study's recommendation and the document it produced. 'Do not build this' is a successful conclusion, not a failure; so is 'abandoned' when the question stopped mattering. Link the features it spawned or killed with study_outcome before concluding.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| actor | No | ||
| status | No | ||
| document_path | No | The write-up, e.g. docs/price_lead_study.md | |
| recommendation | Yes | What to do, and why. State it even if the answer is 'do nothing'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of explaining behavior. It usefully discloses that negative and abandoned outcomes are valid, successful conclusions, and that linking must happen first. However, it does not explicitly state that this tool finalizes or changes the study's status, nor does it describe any side effects or whether the operation is reversible.
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 sentences, each earning its place: the core purpose, the critical semantic nuance about successful conclusions, and the required upstream workflow. Information is front-loaded and there is no repetition or filler.
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 tool with no annotations and no output schema, the description covers the key conceptual traps an agent could get wrong: negative outcomes count as success, abandoned is valid, and feature links must be recorded beforehand. It does not detail every parameter or consequence, but it gives enough context for correct invocation in most cases.
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 50%, so the description must compensate. It adds useful meaning to recommendation, document_path, and status by framing them around conclusions and abandoned outcomes. However, the required id parameter is not explained, and actor is left undocumented, so the compensation is partial.
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 action and resource: 'Record a study's recommendation and the document it produced.' It also clarifies the scope of a successful conclusion, including negative outcomes like 'Do not build this' and 'abandoned.' This clearly differentiates it from sibling tools like study_open, study_show, and study_outcome.
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 contextual guidance: use study_conclude to record the recommendation and document, and explicitly instructs the agent to link spawned/killed features with study_outcome before concluding. It does not explicitly state when not to use the tool or name alternatives beyond study_outcome, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record the method agreed with the principal, BEFORE execution. This is pre-registration and it is the point of the design phase: a method chosen after seeing the data can be selected — consciously or not — for the answer it produces. Call this once, at consensus, and do not execute a study that has no method recorded. Revising a method later is allowed and is counted, because a silently revised method is indistinguishable from a fitted one.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| actor | No | ||
| method | Yes | How the question will actually be answered — the data, the comparison, the unit. | |
| conferral | No | Required. The peer DRAFTS here rather than checks. A method is attacked best by whoever did not write it, and the falsifier is the part a single reasoner is least able to test, because it asks how its own expected answer could be wrong. | |
| falsifier | No | What would show the expected answer is wrong. A study with no stated way to be wrong is advocacy with citations. | |
| decisive_evidence | No | What result would settle it, in either direction, agreed in advance. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and delivers: it explains the pre-registration rationale, that revisions are later allowed and counted, and that a silently revised method is indistinguishable from a fitted one. These are meaningful behavioral facts beyond what the schema provides.
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 dense sentences, each earning its place, with the action and timing front-loaded and the rationale and constraints following. Nothing is redundant or padded.
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?
The schema richly documents the nested conferral object and method, but the description never explains what 'id' refers to, whether this call creates or updates a record, or how a later revision is technically performed. The schema's 'Required' note on conferral also conflicts with the top-level required list, leaving ambiguity.
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 71% and the schema's own parameter descriptions are detailed, so the baseline of 3 applies. The free-text description adds no parameter-level meaning beyond referring to the method, but the schema compensates well.
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?
States a specific verb and resource: 'Record the method agreed with the principal, BEFORE execution.' It clearly frames this as the pre-registration step in the design phase and distinguishes it from execution and outcome tools by naming the artifact and timing.
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?
Explicitly says 'Call this once, at consensus' and 'do not execute a study that has no method recorded,' giving clear when and when-not guidance. It does not name alternative tools, but the context is strong enough to route an agent correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Studies with what each spawned, killed or informed. Check before opening one — an already-answered question does not need answering twice.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| status | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It explains that the return includes relationship metadata (spawned, killed, informed) and frames the tool as a pre-flight check. However, it says nothing about read-only nature, pagination, filtering behavior, or return shape beyond those relation fields.
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?
A single, direct sentence plus an actionable advisory. Every phrase earns its place, though the opening 'Studies with...' is slightly elliptical and could be sharper as 'Lists studies with...'.
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 list tool with two optional parameters and no output schema, this description provides the essential mental model: a relationship-oriented listing used to avoid re-doing answered questions. It falls short on status semantics and return-value details, but the sibling context and enum values partly fill the gaps.
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 description does not explain how the cwd or status parameters affect the result. cwd has a schema description, but status is only given as an enum with no semantic guidance. At 50% schema coverage, the description was expected to compensate for the undocumented status parameter but does not.
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 identifies the resource (studies) and the key content (what each spawned, killed, or informed), making it clear this is a multi-study listing. It is distinguishable from siblings like study_show and study_status by implying a broader relationship-focused overview, though it lacks an explicit verb like 'List all'.
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?
'Check before opening one' explicitly instructs the agent to consult this tool before study_open/study_show to avoid duplicated work. This gives a clear usage context, though it does not explicitly name alternative tools or state conditions when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open an investigation whose deliverable is a document and a decision, not code. Use when a question needs real analysis before anything can sensibly be built — whether an effect is real, which of two designs survives contact with the data, whether something is worth doing at all. A study is NOT a feature: it has no acceptance criteria, and it may correctly conclude 'do not build this'.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| actor | No | ||
| context | No | What prompted it, and what decision waits on it. | |
| question | Yes | The question, stated so it can actually be answered. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It usefully explains conceptual behavior: the deliverable is a document and decision, not code; there are no acceptance criteria; it may conclude 'do not build this'. However, it does not state side effects such as whether a study record is created, what state it enters, what the call returns, or any follow-up needed. This is a noticeable gap for a creation action.
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 tight and front-loaded: purpose first, then usage conditions, then an explicit exclusion. Every sentence earns its place, and there is no redundant filler or restating of the tool name.
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?
Because there is no output schema and no annotations, the description should explain return behavior and effects, but it does not. It gives strong conceptual framing and usage context, yet omits operational details like what a successful open returns and how it connects to study_design/study_status. For a creation command, that leaves an agent with some uncertainty about what to expect.
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 75%, covering cwd, context, and question, while actor is undescribed. The description adds no per-parameter detail, though it does reinforce that 'question' must be genuinely answerable through analysis. It does not compensate for the undocumented actor parameter or provide syntax or format guidance beyond 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 opens with a specific verb and resource: 'Open an investigation', and immediately defines the deliverable as 'a document and a decision, not code'. It explicitly contrasts with feature work, which helps differentiate it from feature_propose and other build-oriented siblings. Among the study_* tools, 'open' clearly signals the creation action.
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 explicitly says 'Use when a question needs real analysis before anything can sensibly be built' and gives concrete examples of such questions. It also provides an exclusion: 'A study is NOT a feature' with criteria that distinguish when this tool is inappropriate. This effectively routes the agent away from feature tools without needing to open their schemas.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record that a study spawned, killed or informed a feature. 'killed' matters as much as 'spawned': a study that closes work off is doing its job, and without the link the reason a feature was dropped disappears — leaving it to be re-proposed by someone who never saw the study.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| note | No | ||
| relation | Yes | ||
| study_id | Yes | ||
| feature_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It says 'Record' implying a write, and explains why recording killed matters, but it doesn't disclose whether repeated calls create duplicates, replace existing outcomes, require special permissions, have side effects on linked features, or what response to expect.
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 sentences with front-loaded purpose. The second sentence earns its place by emphasizing the non-obvious importance of recording killed outcomes, so nothing is bloated or irrelevant.
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 write-style tool with no annotations and no output schema, important operational context is missing: idempotency, duplicate handling, whether a study can have multiple outcomes for the same feature, and what happens after recording. The rationale is well covered, but the invocation consequences are not.
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 only 20%, but the description gives meaning to the central relation values (spawned, killed, informed) and establishes which identifiers are involved. It doesn't elaborate on note or cwd beyond schema, and the exact nuance of 'informed' remains vague.
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 uses a specific verb ('Record') and a clear resource relationship: a study spawning, killing, or informing a feature. It differentiates from generic study lifecycle tools like study_conclude or study_list by naming the outcome relation, though it doesn't explicitly contrast it with a sibling like feature_link.
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?
It gives clear context for when the tool is appropriate: whenever a study has spawned, killed, or informed a feature, and it explicitly stresses that killed outcomes must be recorded as much as spawned ones. It doesn't name exclusions or alternative tools for other link types, but the usage context is concrete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One study and every feature it touched — the provenance view.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavior. It reveals that the tool shows provenance relationships, but says nothing about side effects, permissions, output format, pagination, or error behavior.
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 tight, memorable sentence with no redundant filler. It is appropriately front-loaded, though it reads as a tagline rather than a complete definition.
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?
The description is incomplete for a caller: it lacks any statement about how to identify the study, what the result looks like, and which sibling should be used instead. With no output schema and no annotations, the sole sentence is insufficient.
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 only 50%: cwd is described but the required id property is not. The description only weakly implies that the id identifies the study; it adds no detail about either parameter or how they interact.
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 communicates a specific resource scope: one study plus every feature it touched, framed as a provenance view. This makes it distinguishable from list-style siblings in intent, though it lacks an explicit verb like 'return' or 'display'.
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?
There is no guidance about when to use this tool versus close siblings like study_status, study_list, or feature_history. The description provides context but no exclusions or alternative selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move a study between open, in_progress, concluded and abandoned.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| status | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavior. It correctly implies a state-changing operation, but does not mention transition constraints, idempotency, what happens if a study is moved to the same status, or whether moves can skip statuses. This is a significant gap for a mutation tool.
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 a single sentence with no filler and no redundancy. It front-loads the core action and lists the relevant statuses, making it easy to parse. It is concise without being falsely minimal.
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 tool has no annotations, no output schema, and only partial parameter documentation, the description is incomplete. It omits important context such as the result of the operation, whether all transitions are allowed, and how errors like invalid status or missing study are handled. An agent would need to inspect sibling usages or infer behavior.
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 only 33%, and the description does not compensate for the undocumented 'id' parameter. The status parameter benefits slightly because the description repeats the enum values, but it adds no meaning beyond the schema. The description does not clarify what values are valid targets, what 'id' refers to, or how 'cwd' interacts with the operation.
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 ('move'), a resource ('study'), and the exact domain of statuses ('open, in_progress, concluded and abandoned'). This clearly distinguishes it from sibling study tools like study_open, study_conclude, and study_status, which only handle a subset of transitions.
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 no guidance on when to use this tool versus alternatives such as study_open, study_conclude, or other study-related tools. There are no prerequisites, no examples, and no exclusions, leaving the agent to infer that this is the general status-transition tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Counts by status and goal, pending gates, and which database and tree were read. Progress is two numbers -- done and tracked -- never a ratio: the denominator growing means real work was found, and a percentage would report that as regression.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it explicitly states that progress is never a ratio and explains why a percentage would misreport regression. It also discloses provenance by saying which database and tree were read.
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 sentences, front-loaded with the core counts, and the second sentence earns its place by preventing a common misinterpretation. No wasted words.
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 status tool with no annotations and no output schema, the description explains the return content and a key interpretation trap. It could add explicit read-only/ side-effect phrasing, but 'which database and tree were read' strongly implies a non-mutating status read.
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 single cwd parameter is already fully documented. The description adds no additional parameter-level meaning, matching the baseline for high schema coverage.
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 'Counts' and the exact resources counted: status, goal, pending gates, and database/tree provenance. This clearly distinguishes it from sibling list and mutation tools.
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?
No guidance is given on when to use tracker_status versus siblings like feature_list, gate_list, or study_status. The purpose implies an overview/status role, but no explicit when-to-use or alternative routing is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report that a worker is alive and extend its leases. Silence is what 'stale' means, so a worker that stops heartbeating has its claims expire and its work picked up by someone else. Call this every few minutes while working.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. | |
| goal | No | ||
| worker | Yes | ||
| worktree | No | ||
| session_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and it does real work: it states the side effect (lease extension) and the failure mode (silence to claims expire to work picked up). It stops short of detailing idempotency or what a successful response looks like, but the core runtime semantics are disclosed.
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 sentences, each with a distinct job: action, consequence, and cadence. The most decision-relevant information is front-loaded and there is no filler.
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?
The description captures why and when to heartbeat and the consequence of silence, which is the minimum viable context. It is incomplete for a 5-parameter/no-output-schema tool because it never explains the optional parameters, the required worker value, or the response/error behavior.
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 only 20% (only cwd has a schema description), and the tool description compensates for almost none of that. It adds only the general idea that `worker` identifies the living worker; `goal`, `worktree`, and `session_id` remain unexplained and ambiguous.
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 action ('Report that a worker is alive and extend its leases') and names the resource and effect. The stale-silence explanation differentiates it from one-shot status/list tools like worker_list and checkpoint, so an agent can identify its purpose without reading schemas.
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?
'Call this every few minutes while working' is a direct, explicit trigger condition. It does not name alternative tools or give a when-not-to-call exclusion, but it clearly scopes use to active work sessions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Workers, how long since each was heard from, whether it is stale, and how many features it holds. An idle worker and a working one look identical without this.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory identifying the project and the tree. Defaults to this session's working directory, which in a git worktree is that worktree. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses useful behavioral context: the tool surfaces staleness and feature counts, and explains why this matters. However, it does not specify staleness thresholds, output format, ordering, or side-effect status, though 'list' implies a read-only operation.
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 two concise sentences with no filler. The essential output contents are front-loaded, and the second sentence adds a meaningful rationale for the tool's existence. Every word 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 list tool with one optional parameter and no output schema, the description communicates the key return values and the conceptual need for the tool. It is slightly light on staleness interpretation details, but the information is sufficient for an agent to select and invoke the tool 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?
The only parameter, cwd, has 100% schema description coverage, so the baseline is 3. The description adds nothing about the parameter, but none is needed because the schema already documents its purpose and default 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?
The description clearly identifies the resource (workers) and the information returned (staleness, time since last heartbeat, feature count). It lacks an explicit verb like 'list' or 'show', which keeps it from a 5, but the meaning is unambiguous and it is distinct from sibling worker_heartbeat by describing read-only status reporting.
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 line 'An idle worker and a working one look identical without this' implies a use case: checking worker liveness/status. However, it does not explicitly state when to use worker_list versus alternatives such as worker_heartbeat, nor does it mention any exclusions or preferred contexts.
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.1.0checkpointconfer_digestconfer_historyconfer_recorddb_backupdb_backupsdb_restorederive_featuresderive_gapsderive_listderive_pagederive_reviewdirective_ackdirective_issuedirective_pollfeature_blockedfeature_claimfeature_historyfeature_linkfeature_listfeature_proposefeature_readyfeature_reassignfeature_refine_batchfeature_releasefeature_unblockedfeature_unlinkfeature_unrefinedfeature_updategap_scangate_decidegate_decide_batchgate_listgate_queuegate_raisegate_reconcilegate_reopengoal_definegoal_listgoal_membershipgoal_prunegoal_refinegoal_refine_batchgoal_setgoal_showgoal_unrefinedoz_shutdownparity_gapsparity_scanparity_setproject_boundariesstandupstash_liststash_restorestudy_concludestudy_designstudy_liststudy_openstudy_outcomestudy_showstudy_statustracker_statusworker_heartbeatworker_listScored across 64 tools
Most tools are carefully scoped and the descriptions do a lot of disambiguation work, but several pairs have blurry boundaries: parity_set vs parity_scan both write coverage, study_conclude vs study_status both touch the concluded state, and feature_ready vs feature_unblocked both answer what can be worked next. Agents would often need to read the full descriptions carefully to avoid misselection.
The dominant pattern is domain-prefixed snake_case (feature_, gate_, goal_, study_, derive_, db_, confer_), which is predictable and consistent. Minor deviations like standup, checkpoint, tracker_status, and oz_shutdown do not fit the prefix pattern, but they are few and still readable.
64 tools is an extreme surface for an agent to hold in context and choose among, especially when many are micro-operations like stash_restore, confer_digest, or goal_membership. Some consolidation into composite tools or subcommands would make the set far more usable without losing capability.
The lifecycle coverage is unusually thorough: features, goals, gates, studies, parity, workers, directives, derivations, backups, conferral, and shutdown workflows all have read/write/action counterparts. The main gap is the absence of a single-feature show/get tool for reading one tracked item's full detail, though feature_list likely covers basic lookup and agents can work around it.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Shared project memory that keeps teammates and AI agents aligned across sessions.
The team layer for AI coding agents: shared contracts, collision alerts, E2EE sessions.
Versioned agent memory in your own Postgres: portable context, permissioned, audit trail.
Coordination hub for AI coding agents: message teammates, ask humans, audit every event.
