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

No annotations are provided, so the description carries the full disclosure burden. It correctly implies a non-destructive append but does not mention side effects such as whether the file is created if missing, how title and body are formatted, or what the tool returns.

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

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

A single sentence with no filler; the action and target file are front-loaded. Every word earns its place.

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

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

For a simple two-string append operation, the description is minimally sufficient, but it leaves behavioral questions open and does not differentiate this tool from ralph.append_progress. With no annotations or output schema, the context provided is 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%, and the description does not explain that title is the section heading and body is the section content. The parameter names are suggestive, but the description adds no meaning beyond what the schema already shows.

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 ('append') and a concrete target file ('.ralph/logs/learnings.md'), so an agent can distinguish it from sibling tools by resource. The verb and object are both explicit and unambiguous.

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

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

No guidance is given for when to use this tool versus siblings such as ralph.append_progress or the write_* tools. The sibling set includes another append-type tool, so the absence of selection criteria is a real gap.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It does disclose append semantics and the timestamp behavior, which is useful. However, it does not mention whether the file or directory is auto-created, what happens on repeated calls, error conditions, or return 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 description is a single, tightly written sentence that conveys action, target, and payload characteristics without filler. Everything included 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 one-parameter append tool, this is minimally viable: an agent can infer that it should pass the entry text. However, with no annotations, no output schema, and no usage guidance, a few meaningful gaps remain around exact timestamp handling and when to prefer this tool over siblings.

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 only defines 'entry' as a required string with no description, so the description must compensate. It clarifies that the string is a log entry and implies the tool adds a timestamp, but it is ambiguous whether the caller should include the timestamp themselves. This is partial but not complete compensation.

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 ('Append'), a specific resource ('.ralph/logs/progress.txt'), and the nature of the payload ('a timestamped entry'). This clearly differentiates it from siblings like append_learning by target file and operation.

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

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

The intended use is implied by the tool name and the progress log path, but the description does not explicitly say when to use this tool versus alternatives such as ralph.append_learning or other writing tools. There is no when-to-use or 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, the description carries the full burden of behavioral disclosure. It communicates a precondition ('active task') and the action's effect ('move into Blocked section'), but it does not mention side effects such as status changes, whether the operation is reversible, required permissions, or what happens if the task is already blocked.

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

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

The description is one sentence with no filler, front-loading the action and destination. It is appropriately concise for a simple tool, though the terse phrasing leaves some semantic gaps that are penalized elsewhere.

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

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

Given three parameters, no output schema, and no annotations, the description is not complete enough for an agent to call the tool reliably. It omits how the parameters map to the action, what the required inputs actually mean, and the practical consequences of the operation beyond the literal move.

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 undocumented parameters. It adds a small semantic clue by saying 'with a short reason,' which maps loosely to the 'reason' parameter, but it does not explain what 'text' refers to, when 'taskId' is needed, or how the task is identified or selected.

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 ('Move') and identifies both the resource ('active task') and the destination ('dedicated Blocked section'), so the core purpose is clear. It distinguishes itself from the obvious sibling 'unblock_task' through the 'Blocked' terminology, though it does not explicitly name any sibling.

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

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

The phrase 'active task' implies the intended use case: block tasks that are currently active. However, there is no explicit guidance about when not to use this tool, how it relates to 'set_task_status', or when to prefer 'unblock_task' instead, leaving usage largely inferred.

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 behavioral disclosure. It does reveal file creation, conditional seeding ('if missing'), the normalization flow via ralph.write_prd, and the default config path. However, it does not specify whether existing phase1.sh or prompt files are overwritten, and the sentence 'Configure phase1.sourcePlan in .ralph/config.json' is ambiguous between a tool side effect and a user instruction.

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

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

The description is three dense, efficiently ordered sentences: artifacts created, script execution, config default, and next step. Every sentence earns its place and there is no filler, repetition, or unnecessary detail.

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

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

For an orchestration/setup tool with no output schema and no annotations, the description covers the created files, the shell command to execute, the config mechanism, and the successor tool. The only notable gaps are overwrite behavior and what a successful invocation returns, which are relatively minor for a setup tool.

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

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

Schema description coverage is 100%, so the parameter is already fully documented in the schema. The description mostly restates the sourcePlan semantics and the default path, adding no new syntax or format details. Baseline 3 is appropriate because the schema handles the heavy lifting and the description adds little beyond that.

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 ('Set up Phase 1') and enumerates concrete artifacts from the action: creates .ralph/phase1.sh and .ralph/phase1-prd-prompt.md, and seeds a draft project-plan.md. It also implicitly differentiates from ralph.generate_phase2 by pointing to it as the next step, though it does not contrast against other siblings like ralph.write_prd or ralph.write_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?

The description gives clear operational guidance: run bash .ralph/phase1.sh to normalize the plan into the PRD, and run ralph.generate_phase2 when the PRD is ready. This provides a sequential usage context and a clear next action. It does not explicitly state when NOT to use this tool or list alternative tools, but the phase workflow is evident enough.

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 disclosure burden, and it does well by listing the specific files and directories it creates, stating that Phase 2 reads paths.projectPlan, and adding a prerequisite. It does not state whether existing files would be overwritten, but this is a setup/generation tool where that risk is fairly inferable.

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

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

Four dense sentences with no filler. The main setup action and artifact list are front-loaded, while the remaining sentences cover the prerequisite and the follow-up command. Every sentence earns its place.

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

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

For a one-parameter setup tool with no output schema, this description is complete: it names all artifacts, the configuration default, the precondition that prd.md must exist, and the post-setup execution step. An agent has enough information to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents planFile. The description adds value by explaining that Phase 2 reads paths.projectPlan with a default of .ralph/prd.md and that the referenced plan file must exist first, which helps the agent decide how and when to supply planFile.

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: 'Set up Phase 2' and enumerates the exact artifacts created (.ralph/phase2.sh, config.json, prompt files, specs/, logs/). This clearly identifies it as a Phase 2 scaffolding operation and distinguishes it from generate_phase1 and generate_phase3 by phase and file names.

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 clear context and sequencing: .ralph/prd.md must exist first, then setup occurs, then bash .ralph/phase2.sh should be run. It does not explicitly compare against sibling generate tools, but the Phase 2 naming and prerequisite make the intended usage obvious.

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 present, so the description carries the behavioral disclosure burden. It explains the Phase 3 persona flow, the consensus sign-off, that QA close marks tasks done, and the required input file. It does not detail failure behavior or overwrite semantics, but for a 0-parameter script-setup tool this is reasonably transparent.

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

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

Two dense sentences deliver the key artifact, workflow, file outputs, prerequisite, and command with no filler. The most important information is front-loaded in the first phrase.

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 0-parameter tool with no output schema, the description covers the essential context: prerequisite, action, artifacts, and how to run it. It does not describe the result of running the script in detail, but the operation is simple enough that this is a minor gap.

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

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

The tool has zero parameters and the schema already fully documents this, so the baseline is 4. The description adds useful context about what the script sets up and requires, even though no parameter documentation 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 states a concrete action ('Set up Phase 3') and identifies the exact artifact (.ralph/phase3.sh) plus the workflow it configures. It is clearly distinguished from sibling tools like generate_phase1 and generate_phase2 by naming Phase 3-specific deliverables and prompt files.

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 hard prerequisite ('Requires .ralph/fix_plan.md') and the exact invocation command ('Run bash .ralph/phase3.sh'). It does not explicitly contrast with generate_phase1/phase2, but the Phase 3 label and prerequisite provide enough contextual guidance for an agent to select it appropriately.

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 present, the description carries the full behavioral burden. It states the key constraints upfront: results are limited to one level deep and paths are repo-relative. It does not describe return format or error behavior, but for a simple read-only list operation the essential behavior is 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?

Two short sentences deliver the core scope first, then the workflow context. Every phrase adds information and nothing is wasted.

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

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

The description is sufficient for a single-optional-parameter list tool: it states the depth limit, path expectation, and follow-up action. It omits return shape, but the absence of an output schema is not harmful here because the listing behavior itself is the expected 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 documentation covers the single directory parameter 100%, including that it is repo-relative and defaults to repo root. The description reinforces the repo-relative aspect but adds no syntax, format, or example beyond the schema, so baseline 3 is appropriate.

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

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

The description names a specific action and scope: listing files and directories one level deep under a repo-relative path. This clearly distinguishes it from the sibling ralph.read_file, which reads file contents rather than 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?

It explicitly says to use this during Phase 2 exploration to discover source files, then follow up with ralph.read_file. This gives an agent both the context and the next action, with no competing list-like sibling to confuse.

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 present, so the description carries the full burden. It does disclose a meaningful behavioral trait ('ignores blocked tasks') and implies a read-only 'Return' operation. However, it does not state what happens when no unchecked active task exists, whether the file is modified, or how ordering is determined.

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

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

One sentence with no filler. The primary action and resource are front-loaded, and the blocking filter is neatly appended in parentheses.

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-argument tool, the description provides the essential invocation context: source file, selection criteria, and filtering behavior. It would be slightly better with a note on empty-result behavior or return format, but an agent can call this tool correctly with the given information.

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 100% schema description coverage, so there are no parameter semantics for the description to add. Baseline 4 applies for a zero-parameter tool.

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 concrete verb ('Return'), a specific source ('.ralph/fix_plan.md'), and clear selection criteria ('next unchecked active task', 'ignores blocked tasks'). This distinguishes it from sibling mutation/status tools like set_task_status or block_task.

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

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

The description implies the obvious use case—when the agent needs the next actionable task—but it does not name alternative tools or explicitly state when not to use this tool. With several sibling tools like read_file and read_state that could serve adjacent purposes, usage guidance is only implied, not explicit.

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. It discloses the file scope ('inside the repo') and path convention ('repo-relative'), but does not describe return value, error behavior, or explicitly confirm it has no side effects beyond the verb 'Read' implying them.

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

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

Two sentences with no filler. The core operation is front-loaded, and the phase-specific guidance is concise and useful.

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

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

For a one-parameter, straightforward read operation with full schema coverage, the description is nearly complete. It provides the operation, path convention, and intended phase, but it omits explicit return-value or error details, which would be helpful without an output schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces that relativePath is repo-relative, but it does not add meaning beyond what the schema already states.

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 ('Read'), a specific resource ('any text file inside the repo'), and the required identifier ('repo-relative path'). It is clearly distinguishable from siblings like ralph.list_files and ralph.read_state.

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

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

The description gives clear usage context: 'Use this during Phase 2 to explore source code and inform spec and fix-plan authoring.' It does not explicitly name alternatives or state when not to use it, but the guidance is concrete enough for an agent to know when it applies.

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

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

No annotations are provided, so the description carries the full burden. It clearly indicates a read operation and enumerates the state sections returned. It does not discuss side effects, but the read-only nature is unambiguous and there are no parameters to complicate behavior.

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

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

Two sentences with no filler. The first sentence names the action and contents; the second gives the precise call timing. Every word contributes information.

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

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

For a parameterless read tool with no output schema, the description adequately covers what the tool returns and when to call it. Minor gaps remain, such as clarifying the format of 'log tails' or how 'PRD tail' differs from the spec index, but these are not essential for using the tool correctly.

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

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

The tool has zero parameters and schema coverage is 100%, so no parameter documentation is needed. The description adds useful context about what the returned state contains, which is the appropriate value for a parameterless tool.

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 ('Read') and names the resource ('.ralph state'), then enumerates its contents: config, parsed tasks, spec index, PRD tail, and log tails. This clearly distinguishes the tool from siblings like read_file and list_files by referencing the aggregated .ralph state bundle.

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

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

The description gives explicit timing guidance: 'Call at the start of Phase 2/3 iterations.' It does not explicitly name alternatives or exclusion conditions, but for a read-only state-loading tool, the when-to-use guidance is concrete and 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 disclosure burden. It reveals the destructive nature (Replace the file), the conditional preservation behavior (completed items can be kept via preserveCompleted), and a content-level defer syntax. It does not spell out the exact effect of preserveCompleted:false or mention return values, but the main side effects are reasonably transparent.

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

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

Three short sentences with the core action front-loaded, followed by the phase/flag guidance and the defer syntax. Every sentence contributes distinct information with no filler or redundancy.

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

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

For a simple two-parameter replacement tool with no output schema, the description covers the target file, the replacement semantics, the preserveCompleted flag, and a content-level defer feature. It leaves some details implicit, such as what qualifies as a completed item or what the tool returns, but an agent has enough to call it correctly.

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

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

Schema description coverage is 0%, so the description must supply parameter meaning. It directly explains preserveCompleted (preserve completed items; use true when refining) and gives content-format guidance through the defer comment syntax, giving both parameters useful context beyond their raw names and types.

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

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

The description names the exact resource (.ralph/fix_plan.md) and a specific action (Replace), making the tool's purpose unambiguous. It also differentiates from siblings like write_plan and write_prd by targeting a distinct file with a replace-semantics operation.

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

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

The description gives clear context: in Phase 2/3, use preserveCompleted:true when refining. This is practical guidance for when and how to use the tool, but it does not explicitly name alternatives or state when not to use the tool, 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 to lean on, the description discloses the precise commands run, their order, and the failure behavior ('stop on first failure'). This is strong for a test-execution tool. It does not mention side effects like npm ci modifying dependencies or how timeouts are handled, but the core behavior is transparent.

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

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

A single front-loaded sentence conveys the tool's purpose and exact behavior with zero wasted words. The strict-gate framing comes first, followed by the command details, which is an ideal 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?

For a simple command-runner tool, the description covers the essential command and failure semantics. However, with no output schema, it does not explain what the agent will receive back (exit status, logs, summary), nor does it describe how timeoutSeconds affects execution. This is a noticeable but not severe gap.

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

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

The sole parameter, timeoutSeconds, is not mentioned in the description at all. With 0% schema description coverage, the description should compensate by explaining that this parameter sets an execution timeout, but it does not. The parameter name and default value provide only minimal inferable 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 specifies a concrete action ('Run strict verification gate') and the exact command sequence with execution order ('npm run ci, then npm run test:e2e'). This unambiguously distinguishes it from sibling tools that handle planning, file operations, or task state.

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

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

No explicit guidance is given about when to invoke this tool versus any alternative, nor are prerequisites or exclusions stated. The intended use is only implied by the phrase 'verification gate' and the command names, so an agent has to infer the appropriate 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 the behavioral burden. It discloses the mutation target and a role/phase restriction, but it does not explain failure behavior, whether unchecking is similarly restricted, or any broader authorization or side effects.

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

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

Two sentences deliver the action, target, selection method, and the critical Phase 3 persona restriction. There is no filler, and the most important operational constraint is clearly front-loaded.

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

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

For a simple three-parameter tool with no output schema or annotations, the description covers what it does, where it acts, how to identify tasks, and a key policy restriction. It is slightly incomplete regarding the text-vs-taskId relationship, but it is sufficient for a basic correct call.

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 that text or taskId selects the task and that checked toggles the state, but it does not clarify that text is required while taskId is optional, nor how both interact when supplied.

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 ('Check/uncheck a task') and the exact resource (.ralph/fix_plan.md). This distinguishes it from related task-state siblings like block_task and unblock_task, which imply a different status operation.

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

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

It gives a concrete usage constraint: in Phase 3, only the QA-close persona should call this with checked:true, and only after Dev agrees sign-off. However, it does not explicitly contrast this tool with siblings or state when checked:false 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 must carry the behavioral disclosure burden. It does reveal the state transition from blocked to active and the default unchecked state, which is useful. However, it does not mention side effects, how a task is identified, or what happens if the task is already active.

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 short and front-loads the action, with the behavioral default as a parenthetical. Every word adds information; there is no filler.

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

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

For a tool with no output schema, no annotations, and two undocumented parameters, the description is too sparse. It explains the transition but not the parameters, response behavior, or edge cases, so it is not sufficient for a confident call.

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 never mentions text or taskId. An agent cannot learn what text should contain, what taskId does, or when taskId is required. The description therefore fails to compensate 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 uses the specific verb 'Move' and names the exact resource and destination: a blocked task into the active task list. The parenthetical 'unchecked by default' adds concrete state detail. This clearly distinguishes it from siblings like block_task and set_task_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?

There is no explicit statement about when to call this versus alternatives such as block_task, set_task_status, or next_task. The action is implied by the name and description, but no exclusions, prerequisities, or alternative routing are provided.

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 that the tool can both write and update existing spec files, implying upsert semantics, and it names the target directory. It does not describe overwrite granularity, return values, or side effects, but the core mutating behavior is visible.

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

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

The description is a single sentence with no filler. The action and target path are front-loaded, and the usage guidance follows immediately. Every word earns its place.

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

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

For a simple two-parameter tool, the description provides the essential art: what to do, where files go, and when to call it. However, the lack of parameter format details and any mention of behavior around existing specs leaves gaps that an agent must infer.

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, but it only implies parameter meaning indirectly through 'spec file under .ralph/specs/**'. It does not explain what content format is expected, how relativePath should be structured, or any constraints on either parameter.

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

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

The description uses a specific verb ('Write/update') and a precise resource ('a spec file under .ralph/specs/**'). This clearly distinguishes it from sibling tools like write_plan, write_prd, and write_epic_plan, which target different artifacts.

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

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

It gives explicit usage context: call iteratively during Phase 2 while exploring source files and refining understanding. It does not name alternatives or explicitly say when not to use it, but the phase and iterative workflow guidance are solid.

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 reveals that the tool mutates a file at a specific path, but it does not say whether existing content is fully overwritten or merged, whether the file/directory is created if missing, or what constraints apply to the content. For a write operation with no annotation coverage, this is a significant gap.

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

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

The description is a single front-loaded sentence with zero filler. Every word contributes meaning, and for a tool with one parameter, this level of brevity 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?

The tool is simple (single string parameter, no output schema, no annotations), so the description is minimally adequate: an agent can infer that it should pass epic plan markdown as `content`. However, it omits content format details, overwrite semantics, and any relationship to sibling planning tools, which would be needed for fully confident invocation.

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

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

Schema description coverage is 0%, so the description must compensate, but it never mentions the `content` parameter at all. While the parameter name is somewhat self-explanatory, the description does not clarify expected format (e.g., markdown), structure, or constraints, leaving the agent to guess what a valid epic plan document looks like.

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 pairing: 'Write/update the canonical .ralph/epic_plan.md file.' This clearly identifies the target artifact and distinguishes it from siblings like write_prd or upsert_spec by name and file path. However, the presence of a sibling named write_plan creates some ambiguity that the description does not explicitly resolve.

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 tool's purpose is evident from the description—it is for writing or updating the epic plan file—so when to use it is implied. But there is no explicit guidance about when to prefer this over siblings like write_plan, replace_fix_plan, or upsert_spec, and no exclusions or prerequisites are 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?

With no annotations, the description carries the burden of disclosing side effects. It does disclose the core mutating behavior ('Write or update') and the constrained directory, which is useful. However, it does not explain whether an existing file is fully overwritten, whether directories are created, or what return/error behavior to expect.

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

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

Two concise sentences with no filler. The core purpose and scope are front-loaded, and the usage guidance follows immediately. Every sentence contributes necessary information.

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

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

For a simple 2-parameter write tool, the description covers what the tool does, where files go, and when to use it. The schema covers relativePath. Missing detail about content expectations and return behavior, but given the low complexity and self-explaining parameter names, the description is 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 only 50%: relativePath is documented, but content is not. The description adds general context about planning documents but does not describe expected content format, markdown conventions, or constraints. The parameter names are reasonably self-explaining, so this is a minor but real 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 ('Write or update'), the resource ('a planning document'), and the location ('.github/plans/'). It also adds lifecycle context ('before Phase 1 PRD normalization, or auxiliary planning docs'), which helps separate it from write_prd. However, it does not explicitly contrast with other sibling plan-writing tools like write_epic_plan or upsert_spec.

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

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

The description gives a concrete when-to-use signal: draft plans before Phase 1 PRD normalization or auxiliary planning docs. This is clear workflow context. It does not state exclusions or name alternatives, but the intended timing and document type provide enough guidance for correct 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly says 'write or replace', making the overwrite behavior known, and fixes the file location at .ralph/prd.md. It does not mention formatting, validation, or side effects beyond the file write, but for a single-file write operation this is largely sufficient.

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

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

One sentence, no filler, and the most important facts—action, destination, and usage scope—are front-loaded. Every word earns its place.

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

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

The tool is simple: one string parameter, no output schema, and a single target file. The description covers what, where, and when. It is missing only a bit of guidance on how the content should be formatted or how it relates to sibling documents, which is a minor gap at this complexity level.

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, 'content', has no schema description and the description does not explicitly explain its expected structure beyond the tool's overall purpose. The tool title and phrase 'product requirements document' strongly imply that content is the PRD body, so the meaning is recoverable, but the description adds little explicit semantic detail about format or expectations.

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 ('Write or replace'), an exact target ('.ralph/prd.md'), and the document type ('canonical product requirements document'). This clearly distinguishes it from sibling planning and spec tools like write_plan, write_epic_plan, and upsert_spec.

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

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

The phrase 'Used by the Phase 1 Copilot session only' gives a clear context and an explicit restriction on when this tool should be called. It does not name alternative tools or describe what to use in other phases, but the phase-specific scope is strong enough for an agent to route correctly.

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