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

With no annotations, the description bears full responsibility for behavioral disclosure. It mentions 'best-effort' but does not explain what that implies, nor does it state whether the tool is read-only, requires special permissions, or has any side effects. The lack of detail on safety or impact is a significant gap.

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

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

The description is a single, well-structured sentence that immediately conveys the tool's purpose. It is concise but could be slightly more descriptive without losing efficiency.

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 presence of an output schema, the description need not enumerate return fields, but it should still clarify the scope of 'status' and 'next transition summary.' The description is minimally adequate but leaves ambiguity about what information is actually returned.

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 has zero parameters, and the schema covers 100% of (nonexistent) parameters. The description adds context about the output (status and next transition summary), which is sufficient. Baseline 4 is appropriate.

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

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

The description clearly states it returns current pipeline status and a best-effort next transition summary. It uses a specific verb and resource, but does not explicitly differentiate from sibling tools like notify_orchestrator or pipeline_reset, which are more action-oriented.

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

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

No guidance is provided on when to use this tool versus its siblings, such as pipeline_init or set_pipeline_mode. There is no mention of prerequisites, typical workflow order, or situations where this tool is inappropriate.

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 should disclose behavioral traits. It mentions 'deterministic next transition' but lacks details on side effects, idempotency, auth needs, or effects of multiple calls.

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 efficiently conveys the core action. However, it could include more detail without sacrificing conciseness.

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 (4 parameters, no annotations, output schema not described), the description is severely incomplete. It omits parameter meanings, return behavior, and usage context, making it insufficient for correct invocation.

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

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

Schema description coverage is 0%, yet the description adds no meaning to parameters. It does not explain artefact_path, result_status, result_payload, or stage_completed, leaving the agent without necessary 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?

The description clearly states the tool's purpose: recording stage completion and asking for the next transition. It uses specific verbs and resources, distinguishing it from siblings like get_pipeline_status or satisfy_gate.

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

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

No guidance on when to use this tool versus alternatives. The implication is after stage completion, but no exclusions or comparisons with siblings like satisfy_gate or skip_stage.

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?

Discloses key behaviors: requires confirm=True, overwrites existing file, internal flag _bypass_active_check. No annotations provided, so description carries full burden and does well.

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?

Concise, with first sentence stating purpose followed by bullet-like points. No wasted words, easy to scan.

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

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

Covers behavioral aspects, usage context, and internal flag. Output schema exists for return values. Missing parameter explanations slightly reduce 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%, requiring description to explain parameters. Only confirm and _bypass_active_check are explained; type, feature, project are not described despite being unclear.

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

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

Description clearly states 'Initialise a new pipeline state file from the template', a specific verb+resource. It distinguishes from siblings like pipeline_reset by noting it's for starting a brand-new pipeline.

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 ('starting a brand-new feature or hotfix pipeline') and warns about accidental invocation. Does not explicitly list when not to use, but context is clear.

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 discloses that it resets state, requires confirm=True, and is identical to pipeline_init in behavior. However, it does not detail what gets destroyed (e.g., logs, intermediate data) or authorization prerequisites.

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 covering purpose, distinction from init, and usage scenarios. No fluff, but the third sentence could be merged with the second for tighter structure.

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 (4 params, 2 required) and lack of annotation coverage, the description is adequate for the core purpose but falls short on parameter details. The output schema (not shown) may compensate, but description alone is incomplete.

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 only mentions confirm=True requirement. It does not explain the meaning or purpose of project, feature, or type parameters beyond what the schema provides.

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

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

Clearly states verb (reset) and resource (pipeline state), and explicitly distinguishes it from the sibling tool pipeline_init by noting it is semantically different.

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 clear scenarios for use (next feature after close, restarting failed/stale pipeline) and notes the requirement of confirm=True, but does not explicitly list when not to use or compare to other siblings beyond pipeline_init.

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 provided, so description fully discloses side effects: preserves _notes, increments retry_count, writes to _notes._replay_log[], and the downstream constraint.

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 main action, then constraints, then effects. Every sentence adds value with no redundancy.

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

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

For a tool with 2 required parameters and an output schema, the description covers purpose, usage, constraints, and side effects completely.

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

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

Schema coverage is 100% and schema descriptions already explain both parameters. The description adds little beyond the schema, only providing a slight example for stage_name and noting reason is logged.

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 resets a single stage to not_started for re-execution without clearing the pipeline, distinguishing it from siblings like skip_stage and pipeline_reset.

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 it is only available in supervised mode and cannot be used if a downstream stage has completed, providing clear when-to-use and when-not-to-use 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 full burden. It discloses that the tool returns stdout, stderr, and exit code, mentions output truncation via max_output_chars, timeout behavior, and a Windows-specific pitfall (pytest-xdist causing hangs). This provides adequate transparency for a command execution 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 compact: a one-sentence purpose, a bullet-like usage list, and a short Windows note. It is front-loaded with the key action and output, with no extraneous text. Every sentence serves a purpose.

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 (3 parameters, output schema exists), the description covers use cases, limitations (timeout, truncation), and a platform-specific warning. It is complete enough for an agent to understand invocation and potential issues.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by noting the Windows avoidance of pytest-xdist flags, which enriches the semantics of the 'command' parameter. The schema descriptions are detailed, and the tool description reinforces proper usage without redundancy.

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 explicitly states 'Execute a shell command in the workspace root and return stdout, stderr, exit code.' It uses a specific verb ('execute') and resource ('shell command'), clearly distinguishing it from sibling tools like get_pipeline_status and notify_orchestrator by stating its intended use for pipeline agents running tests, linters, etc.

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 guidance on when to use the tool: 'running tests, linters, formatters, build steps' and explicitly states it is 'not for general chat.' It includes a critical Windows note about avoiding pytest-xdist flags, which helps prevent failures. However, it does not explicitly contrast with alternatives among siblings.

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 must fully disclose behavior. It only states the action (set to satisfied) but omits side effects (e.g., idempotency, required state of the gate, failure conditions, or whether it's destructive). This is insufficient for safe agent invocation.

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

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

The description is a single sentence with no redundancy. It efficiently conveys the core purpose. However, it sacrifices needed detail for brevity, but the dimension focuses on conciseness relative to content, which is 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?

For a mutation tool with no annotations and a single parameter, the description should cover basic usage context (e.g., what a gate is, what satisfied means, preconditions). It does not, leaving the agent underinformed despite the output schema existing.

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 parameter 'gate_name' has no description in the schema (0% coverage). The tool description does not add any explanation of what 'gate_name' refers to, valid values, or constraints. This forces the agent to guess or rely on external knowledge.

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 'Set a supervision gate to satisfied (true)' clearly states the verb ('Set') and the resource ('supervision gate'). It implies a specific action that distinguishes it from siblings like 'get_pipeline_status' or 'skip_stage', but does not explicitly differentiate.

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

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

No guidance on when to use this tool versus alternatives (e.g., when a gate should be satisfied, prerequisites, or when not to use it). The description is too minimal to provide 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?

With no annotations, the description carries full burden for behavioral disclosure. It only states the action without describing side effects, state requirements, or potential destructiveness. This is insufficient for an agent to understand implications.

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

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

The description is a single sentence with no unnecessary words. It is front-loaded with the action and immediately lists the options, making it highly efficient.

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 simplicity (one parameter) and the presence of an output schema, the description provides minimal but adequate context. However, it lacks explanation of the pipeline mode concept or when setting it is appropriate, which would be helpful for an agent navigating 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?

The input schema has 0% coverage (no descriptions or enums for the 'mode' parameter). The description explicitly lists the three acceptable values ('supervised, assisted, or autopilot'), compensating for the schema gap and adding meaning.

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

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

The description clearly states the action (set) and the resource (pipeline mode), and lists the three acceptable values (supervised, assisted, autopilot). It distinguishes from sibling tools like get_pipeline_status (read) or pipeline_init (initialization).

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

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

No guidance is provided on when to use this tool versus alternatives, such as other pipeline control tools. There is no mention of prerequisites, context, or exclusion criteria.

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 full burden. It discloses that gates are auto-approved for skipped stages and describes the return result including current_stage and progress_line, but lacks details on side effects.

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

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

The description is very concise (5 sentences), front-loaded with the main action, and uses clear examples without unnecessary 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 the presence of an output schema, the description adequately covers the tool's effect and return value, but could mention irreversibility or constraints like 'must be current stage' (already implied).

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 has 0% description coverage, and the description adds some context (e.g., reason for skipping) but does not explicitly define expected values for stage_to_skip or fully describe the reason 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 clearly states the action ('Skip the current pipeline stage and advance to the next one') and the resource, distinguishing it from siblings like replay_stage or satisfy_gate.

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 explicit when-to-use examples (e.g., skipping security review for docs-only change) and notes that only the current stage can be skipped, but does not explicitly list when not to use it.

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

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

With no annotations, the description fully explains behavior: a shallow merge at the top level, key replacement or creation, and leaving other keys unchanged. This provides complete transparency for a write operation.

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

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

Four sentences, each purposeful: first states action, second-third give usage guidance, fourth explains behavior. No wasted words; front-loaded with the main purpose.

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

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

For a simple tool with one parameter, the description covers purpose, usage, merge behavior, and why to use it over alternatives. Output schema exists, so return value explanation is not needed. Contextual completeness is excellent.

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

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

Schema coverage is 100% and already documents the 'updates' parameter well. The description adds value by providing an explicit example and clarifying the shallow merge semantics, justifying a score above baseline 3.

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 merges key-value pairs into _notes in pipeline-state.json, with a specific verb and resource. It distinguishes itself from sibling tool editFiles by asserting it is the ONLY correct way to write _notes fields.

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 use (for writing _notes fields) and when not to (do not use editFiles for _notes). Explains the rationale: maintaining a single authoritative writer and preventing concurrent-write conflicts.

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?

Without annotations, the description must fully disclose behavior. It mentions validation and path correction but omits side effects (e.g., whether corrections modify data), failure modes, and outcomes, leaving significant ambiguity.

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 single sentence is concise and front-loaded with the action, but it is too brief to provide structured detail. No wasted words, but lacks substance.

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 potential complexity (validation and correction of file paths), the description is incomplete. It does not explain what validation entails, correction conditions, or return value, even though an output schema exists.

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 explain parameter semantics. It references 'deferred item file paths' but the parameter is an array of generic objects, and the description does not specify expected properties or structure, adding minimal 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 states a specific verb+resource: 'validate deferred item file paths' and 'attempt path correction'. It clearly distinguishes from sibling tools like get_pipeline_status or pipeline_init, which serve different purposes.

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

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

No guidance is provided on when to use this tool versus alternatives, nor any prerequisites or context for invocation. The description lacks usage recommendations.

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