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

With no annotations, the description carries the full burden and does so thoroughly: it explains skipping non-ingested plans, how dead-pid stories are handled via check_story_status, and why an external reap pass is deliberately not wired in. This is detailed, non-obvious behavior that an agent would not otherwise know.

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 purpose is front-loaded and the skip condition is immediately clear. The zombie-reaping note is valuable but contains more incident detail than an agent needs for selection, so the definition is slightly verbose rather than perfectly 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?

For a zero-parameter batch tool with an output schema, the description covers what it does, when to use it, which plans are included, and important behavioral caveats. Nothing essential to calling it correctly 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?

There are zero parameters, so the schema already exhaustively covers the input contract. The description adds relevant context by explaining that no plan name needs to be passed because the tool iterates all ingested plans.

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 advance_pipeline') and a precise resource scope ('every plan that has been ingested'), and distinguishes itself from the per-plan sibling advance_pipeline by emphasizing 'every plan' and the manifest condition. It also clarifies what is excluded (plans without a manifest).

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 clear intended use case: a recurring scheduler that picks up newly ingested plans automatically, and notes the no-hardcoded-plan-name benefit. It does not explicitly name the alternative for single-plan advancement, though 'every plan' strongly implies the boundary with advance_pipeline.

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

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

With no annotations provided, the description carries full responsibility and does so thoroughly. It discloses idempotency, dry-run behavior, per-backend gating with independent dispatch/review gates, interruption/resume semantics, MAX_CONCURRENT_AGENTS cap, and the locked-skip response. This is exceptional 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?

The description is long but every sentence adds essential behavioral context. It is front-loaded with the core purpose, then progressively details gating, concurrency, and locking. There is no filler or redundancy; each clause 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 complex orchestration tool, the description covers all critical aspects: what actions are taken, idempotency, gating logic, concurrency limits, and lock behavior. The existence of an output schema covers return-value details, so nothing essential 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?

The only parameter, plan_name, has zero schema description. The description doesn't explicitly define it, but the tool name and the phrase 'Run one orchestration tick' make it obvious that plan_name identifies the plan to advance. Given the single-parameter simplicity, this is acceptable; a baseline 4 applies due to 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 states a precise verb and resource: 'Run one orchestration tick' and then enumerates the specific actions (dispatch ready stories, advance through test->review->PR, adjudicate merges). It clearly differentiates from siblings like advance_all_plans (one plan vs all) and dispatch_story (single story vs orchestrated batch).

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 it is idempotent and designed for repeated scheduler calls, and describes the skip-on-lock behavior. It doesn't explicitly name alternatives (e.g., 'use advance_all_plans for all plans'), but the one-plan scope is clear from the purpose and the lock behavior.

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

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, and it does so thoroughly: it enumerates the entire merge pipeline (rebase, force-push with --force-with-lease, CI polling with retry, acceptance re-run, merge, branch/worktree cleanup, manifest/ticket update, server restart notice), emphasizes atomic abort-on-failure, and warns that force-push and merge happen regardless of local test runs.

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 long but every sentence earns its place: the core purpose is front-loaded, parameter semantics follow, then the detailed behavioral pipeline, then usage cautions. There is no filler or repetition; the length is justified by the destructive and irreversible nature of the operation.

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's complexity, the absence of annotations, and the presence of an output schema, the description is complete: it covers preconditions, side effects, failure semantics, alternatives, and success/error behavior. Nothing an agent needs to safely decide to call this 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?

The schema has 0% description coverage, so the description must compensate, and it does: plan_name is defined as returned by list_plans or passed to save_plan/ingest_plan, and story_key is defined as the story's key within that plan's manifest with the exact state constraints ('parked' or 'pr_open' with 'APPROVE'). Both parameters receive clear, operational meaning beyond their bare schema types.

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: 'Merge a reviewed story's PR into the default branch, right now, on the caller's explicit approval.' It also clarifies what the tool is not ('not a status check') and distinguishes itself from a plain `gh pr merge`, so an agent can tell exactly what action it performs.

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 states when to use the tool ('only call it once you actually want this specific story merged now'), states the required precondition state ('parked' or 'pr_open' with review_verdict == 'APPROVE'), and names the alternative ('plain `gh pr merge`') while explaining why this tool is preferred. It also warns there is no separate confirmation step.

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

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

No annotations are provided, but the description declares the behavior as identical to checkpoint_story and directs the agent to that tool's docstring for full details. This is sufficient for an alias, though it does not independently describe the behavior here.

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?

Extremely concise, front-loaded with the deprecation status, and every sentence earns its place. It conveys the essential information (alias, identical behavior, preference for the canonical tool) with zero 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?

For a deprecated alias, the description is complete: it tells the agent that the tool is a backward-compatible shim, points to the full documentation, and provides the parameter names. Nothing more is needed 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?

While schema coverage is 0%, the description explicitly lists the parameter names (plan_name/story_key/step/summary/next_hint) and points to the canonical docstring for full semantics. This compensates for the missing inline documentation by directing the agent to the authoritative source.

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 deprecated alias for checkpoint_story, stating it has identical behavior and parameters. This is specific and distinguishes it from the canonical sibling, making the purpose 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?

Explicitly states when to use this tool (backward compatibility only) and when not to (prefer checkpoint_story in new code). It also names the alternative directly, leaving no ambiguity about routing.

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

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

With no annotations, the description carries the burden and mostly meets it: it discloses that the tool commits uncommitted work as a WIP commit and appends to the journal. It does not cover failure behavior or permission requirements, but the principal side effects are explicit.

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, then moves through mechanics, parameters, and usage timing. Every sentence adds decision-relevant detail, including the journal path and step-label constraints, 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 five-parameter mutation tool with no annotations, the description covers what it does, how it mutates state, what each parameter means, and when to call it. The output schema exists for return-value details, so no required context appears to be 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 description coverage is 0%, but the description defines all five parameters in detail, including the journal filename pattern, example step labels, WIP-commit naming impact, and the optional nature of next_hint. This fully compensates for the empty schema descriptions.

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

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

States a specific action (record a durable checkpoint), a scoped resource (a dispatched agent's own progress on a story), and the concrete mechanism (WIP commit + journal append). The 'dispatched agent's own progress' framing distinguishes it from generic checkpoint/story-state siblings like checkpoint or set_story_status.

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?

Gives explicit timing: call after each idempotent step, not mid-step. Also explains the recovery flow via dispatch_story, making it clear when the checkpoint matters and how it ties to the alternative path.

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

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 states that it runs tests in the worktree, reports pass/fail, and explicitly notes it does not auto-merge. This is significant behavioral information. However, it does not disclose what happens if the agent hasn't finished, or any other side effects, leaving some gaps.

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, concise and front-loaded with the primary purpose. It avoids filler and directly states the key behavior. Every sentence adds value, and the structure is optimal for quick scanning.

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 with two parameters and no output schema, but the description leaves gaps: it does not explain the parameters, does not mention what happens when the agent is not complete, and does not differentiate from sibling status tools. It covers the core behavior but lacks contextual details that would help an agent use it correctly in a workflow.

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 0%, so the description must compensate for the lack of parameter documentation. It does not explain what 'plan_name' or 'story_key' refer to, nor how they are used. The agent is left to infer from names alone, which is insufficient given the zero 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 states the verb 'check' and the resource 'whether a dispatched agent has finished', and adds specific behavior (runs tests, reports pass/fail, no auto-merge). This distinguishes it from sibling tools like set_story_status or mark_story_done, which focus on status changes rather than checking and testing.

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: to check if a dispatched agent has finished. It implies the intended workflow (post-dispatch status check) but does not explicitly mention when not to use it or name alternatives. Since it gives clear usage context without exclusions, it earns a 4.

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

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

With no annotations, the description carries the full disclosure burden, and it covers both the mechanism ('headless /cost call') and the side effect ('persist it to USAGE_STATE_PATH'). It could add more about failure behavior or prerequisites, but the core behavioral traits 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?

Single sentence, front-loaded with the primary purpose, and every clause earns its place by adding scope, mechanism, or persistence detail. No redundant text.

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 zero-parameter probe with an output schema, the description covers purpose, scope, mechanism, and persistence. The main gap is the absence of any note about when not to call it or what the persisted state is used for, but this is minor given the low 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 tool takes zero parameters, so the description isn't required to add parameter-level meaning; the baseline for zero-param tools is 4. The description's mention of scope is not parameter documentation but it reinforces what the tool measures.

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 ('Probe'), a concrete resource ('current subscription usage'), and a precise scope ('current session + current week'). This distinguishes it from the unrelated sibling tools and leaves no doubt about what the tool does.

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 makes the invocation context clear: an agent calls this tool when it needs current subscription usage, scoped to session and week. It doesn't name explicit exclusions or alternatives, but no sibling tool overlaps with this usage-checking function.

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

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 so thoroughly. It discloses the success and failure return contracts, includes raw output on parse failures, states that it never raises, and clarifies that it does not persist the plan via save_plan.

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 average, but every paragraph serves a distinct decision point: core action, provider configuration, relationship to the alternative path, save_plan responsibility, and return contract. The main purpose is front-loaded in the first sentence, and there is no obvious 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?

Given one parameter, no annotations, and the complexity of provider selection and output handling, the description is complete. It tells the agent exactly what to pass, what provider will be used, what the return shape is, what failure looks like, and what the agent must do after calling 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?

The schema has 0% description coverage, so the description must define the sole request parameter. It does this by calling it a 'raw goal/feature request', which is sufficient for a single free-form string parameter, though it does not give examples or length/format constraints.

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-resource pair: 'Turn a raw goal/feature request into epics/stories JSON'. It further distinguishes itself from the interactive product-analyst subagent and clarifies that it is a separate decomposition path, so an agent can tell it apart from siblings like save_plan and the Agent tool.

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 explains when to use this tool versus the interactive product-analyst subagent: the interactive path is still the default for Claude-quality decomposition, while this tool is for running decomposition on a local provider when desired. It also gives a clear behavioral instruction: do not expect it to call save_plan; review the output and save it yourself.

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

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 covers the core action (spawn agent), the worktree lifecycle (create vs. reuse), the transition to In Progress, the async completion and PID return, and a detailed explanation of the _plan_lock race condition including a concrete failure example. This is exceptionally transparent and goes beyond typical descriptions.

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, then explains the fresh/interrupted branching, and finally a lengthy race-condition explanation. The race-condition paragraph is detailed but arguably excessive for an agent deciding whether to call the tool; it could be condensed to a caution about locking. Overall it is well-structured but slightly verbose, so a middle score is appropriate.

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 no annotations and no output schema shown, the description covers the essential behavioral aspects: what it does, how it handles different states, the async nature, the returned PID, and the concurrency risk. The only major omission is the meaning of the two parameters, which is a notable gap. Still, for a tool of moderate complexity, it 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?

Schema description coverage is 0%, so the description must compensate by explaining the parameters. It never explicitly defines plan_name or story_key. While the names are somewhat self-explanatory (plan identifier and story key), the description does not add any detail about their format, allowed values, or relationship. For a tool with two required parameters and zero schema coverage, this is a significant 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 opens with a clear verb-resource statement: 'Spawn a headless Claude Code agent to work on a single story.' It then distinguishes fresh versus interrupted stories and explains worktree reuse, which differentiates it from sibling tools like mark_story_in_progress or interrupt_story. The purpose is unambiguous and specific.

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 the tool (for a fresh or interrupted story) and what happens in each case. It does not explicitly name alternatives or say 'use this instead of X,' but the behavioral context (spawning an agent, worktree management) makes the use case evident. It also cautions about the lock race condition, which is relevant to safe usage.

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

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

With no annotations, the description carries the full burden and handles it excellently. It explicitly states 'Pure read - makes no changes and writes nothing', explains the meaning and restart implications of 'restart_required', describes how misconfigured roles surface via an inline 'error' key without raising, and documents the degraded behavior for missing plan manifests. This is far beyond typical behavioral 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 longer than average, but nearly every sentence carries substantive behavioral or parameter semantics. The opening sentence front-loads the core purpose and read-only guarantee. Minor redundancy exists ('Read-only diagnostic snapshot' vs 'Pure read - makes no changes and writes nothing') and the self-referential 'same effect as get_effective_config's plan_name' could be tightened, but overall it is well-organized into scannable paragraphs.

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's complexity and the presence of an output schema, the description covers everything needed to call it correctly: what it returns, how the single optional parameter behaves, error-handling behavior, and restart semantics. The output schema handles return-value structure, so no further description is needed there.

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 0%, so the description must explain plan_name, and it does so thoroughly: optional, layers role_config overrides, missing manifest degrades to no overrides. It also clarifies the semantic distinction between values that require a restart and those that are live immediately, which adds meaning far beyond the raw schema.

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

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

The description names a specific resource ('pipeline's effective configuration') and a specific diagnostic purpose ('Read-only diagnostic snapshot'), then enumerates exactly what it reports: resolved role configs, env vars, provenance, and consulted files. This clearly differentiates it from the sibling tools, which are all mutation or status operations on stories/plans.

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 for the optional plan_name parameter: pass it to layer in role_config overrides, and a missing manifest degrades gracefully instead of raising. It does not explicitly name alternatives or when-not-to-use, but the tool is unique among siblings and its read-only diagnostic role is clear. The phrase 'same effect as get_effective_config's plan_name' is slightly self-referential and confusing, but does not undermine the guidance.

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

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

With no annotations, the description carries the full behavioral burden and does so in detail: it explains the creation order, the optional epic restriction, the local-to-UUID manifest return, and the critical merge-vs-replace semantics on re-ingest. It also discloses the destructive effect of overwrite=True (drops anything not produced by this call), which is exactly the kind of side-effect information an agent needs.

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 action and return, then moves into necessary merge semantics. It is dense and somewhat long, but the complexity of the operation justifies most of the length. Minor parenthetical-heavy passages could be tightened, but no sentence is wholly wasteful.

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 absence of annotations, the presence of an output schema, and the tool's mutation complexity, the description is largely complete: it covers side effects, merge behavior, and return format. The main remaining gap is the missing semantic definition of plan_name and the lack of explicit routing guidance against sibling tools.

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 0%, so the description must compensate for all parameters. It clearly explains only_epics as restricting to specific epic summaries and overwrite=True as restoring wholesale-replace behavior. However, the required plan_name parameter is never explicitly defined (e.g., whether it is a saved plan name, path, or identifier), leaving one of three parameters only implicitly covered.

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: 'Push a saved plan into Plane.' It also describes the resulting actions (creates epics, then linked issues) and the return manifest, giving the agent a precise sense of what the tool does distinct from siblings like save_plan or list_plans.

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?

Implies usage when a plan has been saved and should be pushed into Plane, and it clarifies when to use only_epics and overwrite. However, it does not explicitly name alternatives (save_plan, decompose_plan, patch_plan) or state when not to use this tool, leaving the agent to infer routing from sibling names.

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

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

With no annotations, the description fully discloses behavior: sends SIGTERM (no-op if exited), commits uncommitted work as a checkpoint, marks story 'interrupted' rather than 'failed', leaves worktree and branch in place, and acquires _plan_lock due to a race condition. This is exceptionally transparent about side effects and concurrency concerns.

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 well-structured: the main action is front-loaded, followed by detailed mechanics and a separate paragraph on locking. Each sentence adds value, though the lock explanation is a bit verbose. It is appropriately sized for a tool with this complexity and avoids 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 covers the core behavior, side effects, and concurrency rationale, and the existence of an output schema likely handles return values. However, it does not explain the parameters or state prerequisites (e.g., the story must be currently dispatched). Given the detailed nature, it is mostly complete but leaves parameter semantics unresolved.

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 0%, so the description must compensate by explaining plan_name and story_key. It mentions 'plan' and 'story' in the text but never explicitly defines what these parameters represent or how they are used. An agent would have to infer their meaning from the tool name and context, which is insufficient for unambiguous invocation.

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: 'Stop a dispatched agent and leave its story resumable.' It details the mechanism (SIGTERM, commit, marking interrupted) which clearly distinguishes it from siblings like mark_story_done (which would finalize) or dispatch_story (which starts). The resumability is a unique, well-articulated trait.

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

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

The description clearly implies when to use the tool (to stop a running agent while preserving progress) and mentions that a later dispatch_story call resumes it. However, it does not explicitly state when not to use it (e.g., for permanent termination) or compare against other status-changing siblings like mark_story_done. The context is clear but lacks explicit exclusions.

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

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 it well: it states the tool is read-only and makes no changes, explains the one-to-one correspondence with request_decision calls, lists the fields each entry carries, and clarifies that an empty list is normal rather than an error.

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, then adds parameter semantics, return behavior, and usage guidance in a logical order. Every paragraph earns its place without 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?

Given the low complexity, one parameter, and presence of an output schema, the description covers everything an agent needs: what the log contains, how to read it, when to use it, and what empty results mean. Nothing essential 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 0%, but the description compensates by defining plan_name as the plan's name as returned by list_plans or passed to save_plan/ingest_plan. This gives the agent concrete sources for valid values despite the sparse 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 states a specific verb and resource: return the decision log (audit trail) for a plan, with every ruling made by request_decision, oldest first. It clearly differentiates itself from sibling tools like list_plans and request_decision by focusing on historical rulings rather than plans or new decisions.

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 says to call this before escalating a similar decision with request_decision, or when a human wants to review the overlord's rulings. It does not list exclusions or when-not-to-use conditions, but the intended contexts are clearly described.

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

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

With no annotations, the description carries the full burden. It candidly discloses that results are noisy, that manifest files surface as '.manifest', that story journal/notification logs contribute stems, and that returned names are only candidates, not guaranteed ingestable plans. This is rich and honest behavioral detail.

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 minimal, but every sentence adds distinct value: directory location, no parameters, noisy-stem behavior, candidate semantics, and concrete use cases. It is structured with a clear purpose, caveat, and usage; only mild redundancy about 'not a guarantee' could be trimmed.

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 zero params and the presence of an output schema, the description covers everything needed to call and interpret results: directory source, return stem semantics, noise sources, validity caveat, and practical call scenarios. Nothing important 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?

The tool takes zero parameters and the description explicitly says 'No parameters.' With no params, there is nothing to document; the baseline 4 applies because the description accurately confirms the schema's empty parameter set.

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: 'List plan names found in the plan directory'. It distinguishes itself from fresh/ingestable plan sources by explaining the directory scan includes noisy stems, which differentiates it from sibling tools like list_ready_stories.

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 tells when to call the tool: to check if a plan name is taken before save_plan, or to confirm a plan file landed on disk. It does not name an alternative tool to use instead, but the guidance is clear and actionable.

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

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 delivers: it discloses non-raising behavior for missing manifests, the intentionally limited return shape, exclusion of in_progress/parked/done stories, and the dynamic/volatile nature of the ready list. This goes well beyond what the name alone conveys.

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 informative and front-loaded with the core behavior. It slightly repeats the dependency condition in the final paragraph ('neither is a todo story whose dependencies aren't all done yet') after already stating it in the first sentence, but overall every sentence adds meaningful operational detail.

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

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

The description covers the exact readiness condition, return format, omitted fields, error/missing-manifest behavior, parameter provenance, and temporal validity. With no annotations and only one simple parameter, this is sufficient for an agent to call the tool correctly without needing to infer anything.

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 0% and there is only one parameter, so the description must define plan_name. It does so meaningfully by explaining it is 'the plan's name, as returned by list_plans or passed to save_plan/ingest_plan,' which gives the agent a concrete source and provenance for the value.

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: 'Return the stories in this plan that are unblocked and available to dispatch.' It precisely defines readiness via status == 'todo' and fully-completed dependencies, which clearly differentiates it from siblings like list_plans, check_story_status, and dispatch_story.

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 to use check_story_status for full story records and indicates this tool returns only enough to choose a key for dispatch_story or check_story_status. It also instructs the agent to call again after a dependency completes rather than trusting a stale list, providing clear when-to-use and when-to-recall guidance.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 does so thoroughly. It discloses that the call only records status, describes the no-op/locked behavior with a specific return shape, and explains that a nonexistent story returns {'ok': False, 'error': ...} instead of raising. This gives the agent a clear model of side effects and failure modes.

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 then adds only high-value operational detail. Every sentence carries meaning: parameter provenance, invocation timing, non-behavior, error semantics, and lock handling. 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?

Given the tool's moderate complexity and the presence of an output schema, the description covers everything an agent needs: when to call, what the side effects are, how to handle lock contention, and what happens for invalid stories. The lock-retry guidance is especially valuable because it prevents a false assumption about success.

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 0%, so the description must fully compensate. It explains plan_name as the name returned by list_plans or passed to save_plan/ingest_plan, and story_key as the key within the plan's manifest returned by list_ready_stories or dispatch_story. This is exactly the provenance an agent needs to populate the two required parameters 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 states a specific verb and resource: transition the ticket to In Progress and update the local manifest's story status. It also distinguishes itself from dispatch_story by explicitly pointing out that it does not create a worktree/branch or start an agent, which separates it from nearby sibling 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 timing guidance: use it before writing code, call it once right after dispatch_story, and it is also appropriate after manually claiming a story. It does not enumerate alternatives like set_story_status, but the use context is clear enough for an agent to select this tool correctly.

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

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

With zero annotations, the description carries the full burden and excels: it discloses the atomicity guarantee (acquires the same _plan_lock as the scheduler and dispatch_story), the concurrency race it prevents, and the fail-closed validation that rejects unknown fields before the lock is taken so nothing invalid reaches disk. These are exactly the behavioral traits an agent needs to trust a mutation tool, all beyond what any structured field would reveal.

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 purpose is front-loaded in the first sentence, and each subsequent sentence earns its place: the race explanation justifies why the tool exists, the lock detail establishes the atomicity guarantee, and the fail-closed note covers safety. It runs to four sentences, slightly longer than minimal, but none are filler, so it reads as dense and purposeful rather than verbose.

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 presence of an output schema covers return values, and the description addresses the essential concerns for a patch operation: what can be edited, why it's safe, and the validation boundary. Minor gaps remain - the precise shape of role_config and exact error behavior on rejection aren't detailed - but for a two-parameter mutation tool the description covers the high-risk aspects comprehensively.

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 0%, so the description must compensate for both parameters. It clarifies that fields may only contain role_config and that setting any other top-level field is rejected fail-closed, which maps directly to the 'fields' object parameter. plan_name is implied by context as the plan identifier. It doesn't spell out plan_name's role or role_config's internal shape, but it adds substantial meaning the empty schema lacks, earning a 4.

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 (edit) and resource (plan manifest top-level fields), and immediately narrows scope to 'currently only role_config'. This clearly distinguishes it from sibling patch_story (stories vs plan manifests) and save_plan/ingest_plan (whole-plan creation/import vs targeted field edit). An agent can select it correctly without ambiguity.

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 frames the tool as the correct alternative to hand-editing the manifest JSON, warning of the read-modify-write race with the scheduler's 60s advance_all_plans tick. It clearly states only role_config may be set and every other top-level field is rejected, defining what not to use it for. It stops short of naming specific sibling tools as alternatives for other operations, so it's a 4 rather than a 5.

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

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

No annotations are provided, so the description carries the full burden and delivers rich context: the 60s advance_all_plans tick race, the shared _plan_lock, atomicity with the scheduler and dispatch_story, and the consequence of hand-editing. This is exactly the behavioral context an agent cannot get from schema or annotations.

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

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

Four sentences, front-loaded with the core action and field list, followed by the concurrency rationale. Efficient overall, though the field enumeration is dense and could be tightened; nothing is wasted.

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?

Output schema exists, so return values need not be explained. For a nested-object mutation tool with no annotations and 0% schema coverage, the description supplies the exact editable fields, the excluded field, and the concurrency semantics — everything an agent needs to call it correctly.

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

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

Schema coverage is 0%, so the description must compensate, and it does by enumerating the allowed keys inside the free-form `fields` object (agent_instructions, model, persona, risk, dependencies, acceptance, pr_url, summary, tdd_split, backend) and explicitly excluding `files`. Parameters plan_name and story_key remain undocumented but are self-evident from context.

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 (patch/edit) and resource (a story's plan-authored fields) and enumerates the exact editable fields. It also names the sibling set_story_status for status transitions and ingest_plan for file list changes, so an agent can distinguish it from siblings 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?

Explicitly states when to use this tool (patch plan-authored fields without hand-editing JSON) and when not to (status transitions go through set_story_status; files are not patchable, use ingest_plan instead). Alternatives are named with the condition that selects each.

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

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

With no annotations, the description carries the transparency burden and handles it well: it discloses that in_progress stories are interrupted, checkpointed, and left resumable, and that no background usage is burned. It stops short of describing already-paused behavior or persistence details, but the key side effects are covered.

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

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

Three dense sentences front-load the action and scope, then cover side effects and reversal. No filler, restatement, or redundant schema repetition.

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 one required string parameter and an output schema, the description provides everything needed to invoke it correctly: what is stopped, what is preserved, what happens to in-progress work, and how to undo 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?

The schema has 0% description coverage for the single plan_name parameter, and the description never mentions the parameter by name or its format. However, phrases like 'this one plan' and 'paused plan' make the target of the operation clear enough to compensate at a basic level.

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: pause a single plan so advance_pipeline/advance_all_plans no longer dispatch, review, or merge it. It clearly differentiates the tool from global pipeline operations and from resume_plan.

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 names the sibling tools this operation blocks and clarifies that other plans remain unaffected, which defines the precise use case. It also directs the agent to resume_plan as the paired reversal operation.

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

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

With no annotations, the description carries the full burden: it discloses that this is a write/state-recording operation, the sha format constraint (4-64 hex), the HEAD default, and the success/failure response shape. However, it does not say whether an existing audit record is overwritten (the 'last_audited_sha' field implies it is), nor any permission/auth requirements, leaving key mutation semantics to inference.

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?

Front-loaded purpose sentence, then a clean Parameters/Returns layout with no filler. The Returns block duplicates the existing output schema, which is slight waste, but sizing is reasonable.

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 2-parameter mutation tool with an output schema, the definition covers the purpose, both parameters, and success/failure behavior. The residual gap is the lack of any annotation coverage plus no statement about overwrite behavior or required permissions.

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 0%, so the description must compensate, and it does: repo_root is defined as an absolute path to an existing git directory, and sha as an optional 4-64 hex commit id defaulting to HEAD. That covers both parameters with constraints the bare schema lacks.

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 ('Record'), resource ('repository security-audited'), and scope ('at a given commit'). No sibling in the list does anything similar, so an agent can select it unambiguously from the name plus description.

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?

Usage is implied by the description (call it to record an audit), and the sha default to HEAD hints at the common case, but there is no explicit 'use this when / instead of X' guidance or stated prerequisite. Adequate but with a clear gap.

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

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

With no annotations, the description fully carries the burden. It discloses the side effect ('appended to the plan's decisions log'), the return contract (dict with specified keys), and the failure mode ('Fails open... returns a single-line escalation message... check whether the return value is a str'). This is unusually complete.

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?

Although lengthy, the description is densely packed and well-structured: purpose first, then parameter semantics, then usage, then failure handling. Every sentence contributes actionable information, and the return-type caveat is front-loaded in the failure paragraph.

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 complete standalone description despite having no annotations. It covers what the tool does, when to call it, all parameter meanings, the success return format, the failure return format, and how to distinguish the two. An agent has everything needed 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 0%, but the description documents every parameter in detail. It explains that options must be mutually exclusive plain strings selected verbatim, and that context should be supplied whenever the bare question is ambiguous. This adds meaning far beyond the bare 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: 'Escalate a blocking decision to the overlord, which rules on the user's behalf per the decision policy.' It clearly distinguishes this tool from the siblings by focusing on obtaining a decision rather than modifying stories, plans, or statuses.

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 states when to call it: 'Call this from a story agent when you are blocked on a choice the user would normally make; do not guess.' This gives a clear trigger condition and tells the agent not to guess, which effectively directs behavior away from alternatives.

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

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

There are no annotations, so the description must carry the behavioral burden. It discloses the timing (next advance_pipeline tick) and the effect (stories eligible for dispatch/review/merge), but does not discuss reversibility, side effects, or whether there are any prerequisites beyond having a paused plan. This is a basic resume operation, and the description adds some context beyond just 'resume'.

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 that immediately states the primary action (clear a pause) and the consequence (stories become eligible). No filler words; every part carries 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 is simple with one parameter and no output schema expectations explained, but an output schema exists (possibly indicating a return value). The description could mention what the response looks like, but given the tool's simplicity and the known pipeline context, it is largely complete for an agent to use 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?

With only one parameter, plan_name, and 0% schema description coverage, the description provides no additional meaning beyond the schema. Since the parameter name is self-explanatory, the baseline of 3 is appropriate; no further compensation is needed.

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 the tool's purpose: clearing a pause set by pause_plan, and its effect: making stories eligible for dispatch/review/merge on the next advance_pipeline tick. It references the specific sibling (pause_plan) and the pipeline mechanic, distinguishing it from other 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 explains the intended use case: resuming a plan that was paused. It implicitly indicates it should be used after pause_plan, but doesn't explicitly state when not to use it or list alternatives. However, given the clear pair with pause_plan, the guidance is sufficient.

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

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

With no annotations, the description carries the full burden, and it delivers: it discloses the concrete side effects (opens PR via gh, sets status to pr_open or changes_requested), explicitly states it does not merge, and explains no-op behavior for invalid statuses. This is strong behavioral 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?

Two tightly packed paragraphs that front-load the main behavior, then add the critical precondition and exclusion. Every sentence adds usable 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 tool with an output schema, the description covers the essential call-time facts: action, status transitions, non-merge guarantee, and invalid-call handling. It also references the README for deeper review/merge detail, so an agent has enough to invoke it safely.

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 0% and the description does not define plan_name or story_key beyond their names. The general story/status context helps indirectly, but the required parameters are left mostly implicit.

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: running the code-reviewer persona over a dispatched story's branch. It clearly distinguishes itself from merge-related siblings by explicitly saying 'Does not merge — merge is the overlord's 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?

Gives an explicit precondition: only reviewable when story status is 'tests_passed', and any other status is a no-op skip. It even anticipates stale/duplicate racing calls and points to README for more context, making when-to-use versus when-to-avoid unmistakable.

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

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

With no annotations, the description carries the full burden and excels. It discloses key behavioral traits: the overwriting of repo_root when workspace is supplied (WS-11), that the tool never resolves or rewrites plan_json itself, and that it deliberately does not fall back to the dashboard's persisted workspace, explaining the separate-process rationale. These details exceed what annotations would typically cover and prevent misleading assumptions.

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 typical but well-structured: purpose, format, then a detailed workspace behavior paragraph. The rationale for the no-fallback decision is valuable and earns its place. It is front-loaded with the core purpose and scoping before diving into edge cases. No wasted sentences.

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 complexity (optional workspace, overwriting, process boundary), the description covers the critical aspects: the JSON schema, the overwriting rule, the fallback decision. An output schema exists to document return values, so that omission is acceptable. It does not address error conditions or interactions with siblings beyond the ingestion hint, but for a save operation the provided details are largely sufficient.

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

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

Schema coverage is 0%, so the description must compensate. It provides extensive semantics for workspace (validation, overwriting behavior, fallback rationale) and clarifies plan_json's required schema. However, plan_name is not explicitly described beyond being a required string, though its meaning as a name is likely inferred. The description adds significant value for two of three parameters, nearly fully compensating for the schema 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 states the action: 'Save a generated project plan to disk.' It specifies the expected JSON format and differentiates from ingestion by noting 'so the user can review before ingestion,' distinguishing it from the sibling ingest_plan. The verb, resource, and purpose are all explicit.

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: 'Call this after generating a plan so the user can review before ingestion.' This implies the correct sequence (generate → save → review → ingest) and indicates when to use it. It does not name alternative tools explicitly, but the 'before ingestion' phrase sets the stage, and the workspace behavior explains when to omit or supply it. No explicit exclusions are given, but the guidance is sufficient.

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

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

With no annotations, the description carries the behavioral burden and does well by disclosing that it acquires _plan_lock and only accepts pipeline-defined statuses. This tells the agent about locking side effects and invariants. It does not cover possible failures or permission requirements, but the key behavioral constraints are present.

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 primary action and includes an example before adding lock and status constraints. The status list is long but necessary because the schema lacks enums. Minor indirectness ('for the same reason patch_story does') keeps it from being perfectly self-contained.

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 an output schema, so return-value details are not required. The description gives enough context for a correct call: what the tool does, the exact allowed statuses, an example use case, and lock behavior. The only gaps are minor details about the plan/story parameters and failure conditions.

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 0% and no enum metadata exists, but the description supplies the complete allowed status set, which is the critical parameter meaning. plan_name and story_key are left to their self-explanatory titles, and the description's story/plan context partially covers them. This is solid compensation for a low-coverage 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 states a specific action ('Transition a story to an explicit status') and contrasts it with hand-editing the manifest JSON. The fixed status list and 'sanctioned status change' clarify exactly what this tool is for, making it distinguishable from related story tools by defining its scope rather than by 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 gives a concrete usage example ('resetting a parked story to interrupted so the scheduler retries it') and says the tool is the sanctioned path rather than inventing state. It does not explicitly name alternative sibling tools or state when not to use it, so it lacks full exclusion guidance.

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