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, the description carries the full burden of disclosing effects and side effects. It does not mention what changes approving a merge makes, whether it is idempotent, what permissions are needed, or what the output indicates. 'Delegating to PipelineService' is an implementation detail, not behavioral information.

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 brief, but brevity is not the same as conciseness here because almost all useful substance is absent. The phrase 'by delegating to PipelineService' adds no practically useful information and reads as filler rather than an earned 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?

For a two-parameter tool with no annotations and no parameter documentation, the description is severely incomplete. Even with an output schema present, the agent cannot determine what action is actually performed on the referenced plan or story, when it should be invoked, or what the result means.

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 compensate. It does not explain how plan_name and story_key are used, why both are required, or what valid values look like. The meaning of these parameters is entirely unspecified.

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 'Approve a merge' is essentially a restatement of the tool name 'approve_merge', with the only additional detail being the implementation note 'by delegating to PipelineService'. It does not define what a merge is in this domain or differentiate the action from related pipeline or plan operations.

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 sibling tools such as advance_pipeline, review_story, or set_story_status. There are no preconditions, timing cues, or alternative routing hints.

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 well: it discloses both side effects (creating a WIP commit and appending to the journal). It does not mention edge cases like permissions or failure behavior, but the core behavioral disclosure is solid.

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: the first defines the action and side effects, the second gives the calling convention and purpose. Every clause earns its place and the key verb 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?

The description covers what the tool does and when to call it, and an output schema exists so return values need not be described. However, because there are no annotations and schema descriptions are absent, the incomplete parameter semantics and lack of sibling differentiation leave the overall picture only partially 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 for the 5 parameters. It only indirectly clarifies 'step' and 'story' through the usage context, and does not explain plan_name, summary, or next_hint. That is a meaningful 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 action: record a durable checkpoint, commit WIP work, and append a journal entry. It names the exact resources involved (worktree, plan.story.journal.json) and the behavior is clearly distinct from the sibling plan/story management 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?

It explicitly says when to call it: 'after completing each idempotent step of a story'. It also explains the benefit of doing so (resume after kill). It does not name alternative tools or give when-not-to-use guidance, 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.

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 provided, the description carries the full behavioral burden and does so thoroughly. It explicitly states pure read semantics, no writes, how restart_required is determined, which layers are live vs require restart, and how misconfigured roles are reported inline without raising. It also discloses degradation behavior for nonexistent plan manifests.

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 each sentence adds a distinct behavioral fact: read-only guarantee, restart semantics, error handling, and plan_name semantics. It is front-loaded with the core purpose and organized into logical paragraphs, so the density is justified and easy to parse.

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, the presence of an output schema, and the complete absence of annotations, the description provides everything an agent needs to invoke it correctly: what it returns, how it errors, when restarts are needed, and how the optional parameter behaves. No critical behavioral gap remains.

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 all meaning must come from the description. The description explains plan_name's effect in detail: it layers in the plan's role_config overrides, matches get_role_config's plan_name behavior, and degrades gracefully when the manifest doesn't exist. This goes far beyond the bare schema definition.

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: 'Read-only diagnostic snapshot of the pipeline's effective configuration'. It enumerates exactly what the snapshot contains (roles, env vars, ignored vars, config files), and it distinguishes itself from the sibling get_role_config by describing how plan_name behaves relative to it.

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: when you need the effective resolved configuration and provenance across roles, env vars, and config files. It also explains the optional plan_name behavior and compares it to get_role_config. It does not explicitly say 'do not use this when...', but the diagnostic framing and sibling contrast provide sufficient usage context.

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?

Since no annotations are provided, the description carries full behavioral burden. It explicitly states 'Pure read; makes no changes' and explains a non-obvious nuance about planner resolution (not reproducing the mirror fallback). This level of transparency about what the tool does and does not do is exemplary.

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 main purpose is front-loaded in the first sentence, and the second paragraph is a necessary caveat about planner behavior. While a bit verbose, every sentence adds value and there is no fluff. The structure is logical, though slightly longer than strictly needed.

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 purpose, inputs, and a key behavioral caveat. An output schema exists, so return format does not need elaboration. For a complex config-resolution tool, the description gives an agent everything needed to call it correctly and interpret the result.

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. It explains the only parameter (plan_name) by stating 'pass plan_name to include it', giving meaningful context beyond the bare schema. It does not detail format or constraints, but for a single optional string parameter, this is sufficient.

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 action (show resolved provider/model), the resource (all pipeline roles), and the inputs (env vars, model_registry.json, optional plan_name). It is specific and distinct from siblings like get_effective_config by enumerating the exact roles covered and the resolution layers.

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 clear use case: 'check what a plan will actually run on *before* executing it'. This establishes when to use the tool, but it does not explicitly contrast with alternative config tools (e.g., get_effective_config) or state when not to use it. No exclusions are mentioned, so it falls 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.

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 excellently. It discloses idempotent merge semantics: untouched epics/stories are preserved, existing story authored fields are refreshed while runtime state is kept, and unrelated manifest keys carry over. It also warns that overwrite=True restores destructive wholesale-replace 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?

The first sentence front-loads the verb, resource, and order of operations; the rest supplies necessary edge-case behavior without filler. Though dense, every sentence adds a distinct fact an agent needs to call the tool correctly.

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 stateful, potentially destructive tool with no annotations, the description covers creation order, optional restriction, returned manifest, and re-ingestion behavior. The output schema exists, and the manifest return is still summarized, so no critical invocation context 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 description coverage is 0%, so the description must compensate. It explains the two non-obvious parameters: only_epics restricts to specific epic summaries, and overwrite toggles old wholesale-replace behavior. plan_name is not explicitly described but is self-evident as the identifier of the saved plan to ingest.

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 and workflow: 'Push a saved plan into Plane. Creates epics first, then issues linked to their parent epic.' This clearly distinguishes ingest_plan from sibling tools like save_plan, decompose_plan, or advance_all_plans, and makes its role unmistakable.

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 trigger is clear: after a plan has been saved, this tool pushes it into Plane and optionally restricts ingestion via only_epics. It does not explicitly name sibling alternatives or exclusions, but the context is strong enough for an agent to determine when to call it.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'Return', implying a read operation, but does not mention ordering of entries, whether the log is complete, or any access requirements. Critical behavioral traits like read-only guarantees or limitations are absent.

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, front-loaded sentence that states the action, resource, and a clarifying parenthetical. Every word contributes value with no 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?

The tool is simple (one required parameter) and an output schema exists, so the description need not detail return values. It conveys the core purpose and audit trail intent, which is likely sufficient for a read-only list operation. Minor omissions like error cases are acceptable 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?

Schema description coverage is 0%, so the description must compensate. The phrase 'for a plan' indicates that plan_name specifies which plan's log to retrieve, which is minimal but relevant. However, no additional details are given about valid values, defaults, or relation to existing 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 clearly states the specific action ('Return the overlord decision log for a plan') and adds the clarifying 'audit trail' note. It is distinct from sibling tools like request_decision or review_story, which deal with creating or reviewing decisions, not listing 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 description provides no guidance on when to use this tool relative to alternatives. It does not mention prerequisites, such as requiring an existing plan, or differentiate it from other list/read tools like list_plans. No context is given on typical use cases.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no 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?

Tool has no 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?

Tool has no description.

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 is the only behavioral disclosure. It clearly states the operation is a read-only retrieval ('Return stories...') with explicit filtering criteria. It does not discuss potential side effects, but for a list operation the word 'Return' plus the use context are sufficient for an agent to infer non-mutation.

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 two sentences: the first defines the behavior and criteria, the second gives usage guidance. Every word is purposeful and the meaning is dense, with no redundancy 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?

The tool is simple (one required parameter) and an output schema is present, so return values need not be described. The description covers the core behavior and intended use. The only meaningful gap is the plan_name parameter, which goes unmentioned, but this does not cripple the overall completeness.

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. The description never mentions plan_name, and the schema only provides the name and required flag. An agent must infer from the tool name and 'stories' that plan_name selects the plan whose ready stories are listed. This is a real gap for a required 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 uses a specific verb ('Return'), a resource ('stories'), and explicit criteria ('dependencies are satisfied' and 'still in To Do'). This precisely defines the tool's purpose and differentiates it from siblings like dispatch_story or mark_story_in_progress, which operate on stories rather than list 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 second sentence, 'Use this to decide what to dispatch next,' explicitly gives the context and timing for invoking the tool. It does not mention alternatives or exclusions, but the guidance is clear enough for an agent to know 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.

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

With no annotations, the description carries the behavioral burden. It discloses the main effects—marking the story Done and updating the local manifest—but does not address reversibility, failure conditions, or any other side effects. It is minimally transparent but not misleading.

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. It front-loads the core action and then adds the critical precondition, making it highly concise and well structured.

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 two required parameters and no parameter docs, and the description does not clarify them. It provides a useful precondition but not enough information to confidently invoke the tool correctly in all contexts.

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 and the description does not explain plan_name or story_key at all. It adds no meaning beyond the parameter names, leaving the agent to guess what values these should take.

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 action: transition a ticket/story to Done and update the local manifest. It is specific and not a tautology, though it does not explicitly contrast with siblings like set_story_status or mark_story_in_progress.

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 condition: only after reviewing and merging the agent's PR. It does not mention when not to use the tool or point to 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.

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

No annotations are provided, so the description carries the burden of disclosing behavior. It explicitly names two side effects: ticket status transition and local manifest update. However, it omits preconditions, error behavior, reversibility, and any other consequences of this mutation.

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 concise sentences that front-load the action and then provide usage context. There is no filler, 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?

The core action and when to use it are covered, and an output schema exists for return-value details. However, the description leaves gaps around parameter semantics and how this tool relates to sibling tools like set_story_status, making it only moderately complete for tool selection.

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 should compensate for missing parameter documentation. It does not explain what plan_name or story_key mean beyond their self-explanatory names, leaving the agent to infer the relationship between a plan and a story.

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-resource action: transition the ticket to In Progress and update the local manifest. It is understandable and distinguishes from mark_story_done by the status direction, though it does not explicitly differentiate itself from 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?

The description provides a clear usage context: use this before writing any code for a story. It lacks explicit when-not-to-use guidance or alternative recommendations, but the trigger condition is clear enough to guide selection.

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?

Despite having no annotations, the description discloses important behavioral details: it acquires the _plan_lock for atomicity, it can only modify the listed fields, and it is safe with respect to the scheduler's tick. This is more than adequate given the lack of annotations.

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

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

The description is concise and well-structured. It starts with the core purpose, then explains the key behavioral details (locking, allowed fields, exclusion). Every sentence adds value, and the format is scannable.

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 moderately complex (nested object fields, required parameters) and has an output schema, so the description doesn't need to explain return values. It covers the most critical context: what fields can be edited, why locking matters, and which alternative to use for status changes. The only gap is a bit more detail on parameter syntax, but it's mostly 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 has no description coverage (0%), so the description must carry the burden for parameter semantics. It does mention the 'fields' parameter by listing the allowed fields, but it does not explain the format of plan_name or story_key, or what the fields object should look like beyond the field names. This is partial compensation, but could be more explicit.

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: 'Edit a story's plan-authored fields' and lists the specific fields it can edit. It distinguishes itself from other tools by emphasizing that it edits fields without hand-editing the manifest JSON and that status transitions are handled elsewhere.

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 provides usage guidance: it says when to use this tool (for editing specific fields) and when not to use it (for status transitions, which go through set_story_status). It also warns against hand-editing the manifest JSON, effectively telling the agent to use this tool instead.

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 the ruling is 'appended to the plan's decisions log (audit trail) and returned,' which informs the agent of the side effect and output. It does not mention potential errors, permissions, or reversibility, but the core behavior is transparent enough for a decision-request 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, tightly packed with the core action, result, and usage condition. It is front-loaded with the verb and resource, and each sentence earns its place. There is no redundant or filler 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?

The description explains the purpose, when to use, and the outcome (ruling appended to log and returned). However, it omits parameter semantics and does not mention any preconditions or failure scenarios. Given the output schema exists, return format is covered, but the missing parameter guidance is a significant gap for a tool with 5 parameters.

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 provides no information about the parameters. The names (plan_name, story_key, question, options, context) are somewhat self-explanatory but not fully defined. For example, what exactly constitutes 'options' or the expected format of 'context' is unclear. The description fails to compensate for the lack of schema documentation.

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: 'Escalate a blocking decision to the overlord, which rules on the user's behalf per the decision policy.' It specifies the action, the resource (overlord), and the trigger condition ('when you are blocked on a choice the user would normally make'). This is distinct from siblings like list_decisions or review_story, which have different intents.

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 explicit guidance on when to use: 'Call this from a story agent when you are blocked on a choice the user would normally make.' It does not explicitly mention when not to use or list alternatives, but the conditional context is clear. A sibling like review_story might be used for non-blocking review, but this is not stated.

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.