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

The destructiveHint annotation already flags this as a write/destructive operation, and the description adds real value beyond it: it names exactly what is removed (the saved checkpoint) and the confirm=true guard that must be satisfied. It does not state reversibility or whether the checkpoint can be recovered.

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 plus a short clause, with the destructive action front-loaded and the precondition attached immediately after. 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?

For a two-parameter destructive tool with annotations covering the safety profile and no output schema, the description supplies the key missing piece (confirm=true). It omits recovery/rollback behavior, which would be the only remaining 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?

Schema coverage is 50% (projectPath is documented, confirm has no schema description), so the description compensates by explaining that confirm must be true. The purpose of the confirmation gate is implied rather than spelled out, but the added meaning exceeds the schema alone.

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

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

States a specific verb and resource ('Delete the saved checkpoint for a project'), which is clearly distinguishable from save_handoff/update_handoff/get_handoff siblings by the destructive verb. It stops short of explicitly naming alternatives, so it is clear but not maximally differentiated.

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 a concrete usage context ('after the task is done') and a hard precondition ('Requires confirm=true'). It does not name when NOT to use it or point to an alternative tool, so it falls just 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?

With no annotations, the description carries the full behavioral burden. It usefully discloses the target file path and a critical guard (refuses to overwrite unless overwrite=true), but omits other important behaviors such as whether it creates the file if missing, permission requirements, or what happens to existing content.

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 that states the action, target location, and overwrite guard with zero wasted words. The structure makes the key behavior immediately 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?

For a simple write tool with no output schema or annotations, the description covers the destination and overwrite behavior but leaves a significant ambiguity: it writes 'the checkpoint' without explaining where that checkpoint data comes from, since no checkpoint parameter exists. It also omits return value information and usage context relative to 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?

Schema coverage is only 50%, but the description compensates by explaining the undocumented overwrite parameter's effect and default behavior. The projectPath parameter is already well documented in the schema as an absolute path, so all parameters now have useful semantics.

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 (write) and resource (the checkpoint to HANDOFF.md in the project root), making it clear this is a file-export tool rather than a state mutation. However, it does not explicitly differentiate itself from siblings like save_handoff or update_handoff, leaving the agent to infer the distinction.

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 when-to-use guidance, prerequisites, or alternatives. It explains the overwrite behavior but does not say when this tool should be chosen over save_handoff, update_handoff, or prepare_handoff.

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?

The readOnlyHint annotation already establishes this as a safe read, so the description's main addition is the 'raw ... (JSON)' framing, which usefully signals unprocessed output versus a resumed session. It does not disclose size, pagination, or what happens if no checkpoint exists — gaps that matter but are modest for a single-parameter read.

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

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

Two short sentences, both load-bearing: the first defines the action and output, the second handles sibling routing. Nothing redundant and the core purpose is front-loaded.

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

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

For a simple single-parameter read with no output schema, the description covers what the tool returns (raw JSON checkpoint) and when to prefer an alternative. Only minor gaps remain, such as the no-checkpoint case and whether the output is a full session state.

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

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

Schema description coverage is 100% and projectPath is documented as 'Absolute path of the workspace/project root,' so the schema carries the burden. The description adds no further meaning about the path (e.g., whether relative paths work or how it is resolved), making this a 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?

States a specific verb (Read) and resource (raw saved checkpoint), plus the return format (JSON) and scope (for a project). It also implicitly separates itself from the sibling resume_task, so an agent can tell the two apart without opening schemas.

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

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

Explicitly routes the agent: 'Prefer resume_task when starting a session,' naming the alternative and the condition that selects it. It stops short of stating the positive when-to-use case (e.g., when you need raw JSON for inspection or tooling), so it is clear context rather than a full when/when-not rule.

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?

The readOnlyHint annotation already establishes the safety profile, and the description usefully confirms and extends it by specifying 'Read-only' and enumerating the exact refs/fields inspected. It also discloses negative behavior (no source file or session log reads), which is real added context, though it omits failure modes such as behavior when the path is not a Git repository.

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

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

Two short sentences with zero filler: the primary behavior and the exclusions are both front-loaded. Every clause carries information an agent needs.

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

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

With no output schema, the description compensates by enumerating the return content (branch, HEAD, short status, diff stat), which is sufficient for an agent to know what it gets back. What is missing is edge-case behavior such as a non-Git directory or a path that does not exist.

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 is a single parameter with 100% schema description coverage, so the schema already fully documents projectPath as an absolute path to the workspace root. The description adds no format, resolution, or edge-case detail beyond that, so the baseline 3 applies.

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

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

The description names the exact data it returns (Git branch, HEAD, short status, diff stat) and scopes it to the project, which is a specific verb+resource statement. It further delineates itself by stating what it does NOT cover ('Does not read source files or session logs'), so an agent can distinguish its remit from the handoff/task siblings without opening schemas.

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

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

Usage is only implied: an agent infers it should call this when it needs repository state, and the negative scoping ('does not read source files or session logs') hints at when not to use it. However, no sibling tool is named as an alternative and no explicit when-to-use condition is given.

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 does disclose non-obvious merge semantics: completedStep is relocated from nextSteps to completed on text match, and lists are appended without duplicates. It does not say where the data is persisted, whether non-list fields are overwritten, or what the call returns, leaving some behavioral gaps.

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

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

Three tight sentences with zero filler; the invocation-frequency rule is front-loaded ahead of the merge mechanics, and every sentence conveys information an agent needs.

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 nine-parameter write tool with no annotations and no output schema, the description covers timing and merge behavior but omits what the call returns, where the checkpoint is stored, and how it relates to the other eight handoff tools. Adequate but with clear gaps.

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

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

Schema description coverage is already 89%, so baseline is 3, but the description adds genuine semantics the schema lacks: how completedStep and nextSteps interact and the append/dedupe rule applied to list parameters. It adds no field-level detail for status, decisions, tests, or changedFiles beyond what the schema 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 identifies the tool as a 'cheap, frequent checkpoint' that records step progress, which is a specific enough resource/action for an agent to understand. However, it never names or contrasts itself against siblings like save_handoff or update_handoff, which is the main ambiguity given nine closely related handoff 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?

'Call after EVERY meaningful step, because a usage limit can end your session at any time' gives an explicit trigger and rationale for invocation frequency. It lacks any when-not guidance or a pointer to an alternative sibling for heavier or final-state persistence.

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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds meaningful behavioral context by identifying the output as a continuation prompt and clarifying that it does not message agents, though it omits details such as whether any file is written or what the prompt contains.

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

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

The description is two compact sentences with no wasted words. It front-loads the core action, then appends the use case and a key behavioral constraint, making it easy to scan.

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

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

For a simple two-parameter read-only tool, the description is complete enough. It explains what is produced, the intended scenario, and a boundary behavior, and annotations cover the safety profile, so no critical information 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 100%, so projectPath and targetAgent are fully documented in the schema. The description adds no parameter-level meaning beyond what the schema already provides, which is the expected baseline when schema coverage is high.

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: 'Build a continuation prompt the user can paste into another agent.' It distinguishes the output from sibling tools by emphasizing a pasteable prompt for a target agent and explicitly noting 'Does not message agents,' which separates it from handoff persistence, retrieval, and messaging behaviors.

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 provides a clear context for use: 'useful when that agent has no MCP access.' This tells the agent when this tool is appropriate, but it does not explicitly name alternative siblings such as export_handoff_markdown or save_handoff for other scenarios.

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 does well: it discloses that it writes a side effect ('Records in the timeline that you resumed') and enumerates the returned payload. It omits failure behavior (e.g., what happens when no checkpoint exists) and any permission/rate constraints, keeping it from a 5.

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 imperative lead ('CALL THIS FIRST') is front-loaded and the text is largely free of filler. The main sentence is long and clause-heavy, but each clause adds distinct payload information, so it remains efficient overall.

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 session-bootstrap tool with no output schema and no annotations, the description covers what is returned and the write side effect well. It leaves out edge cases such as the no-checkpoint state, a minor gap rather than a blocking one.

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

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

Schema description coverage is 100%, so the schema already documents projectPath, agent, and detail including the enum and default. The description adds no param-level meaning beyond that, which matches the baseline-3 rule.

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: it resumes a task by returning the previous agent's saved checkpoint plus post-checkpoint activity. It's very concrete about what comes back (checkpoint, hook captures, Git state, later work). It doesn't explicitly differentiate itself from the close sibling get_handoff, so it stops short of a 5.

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

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

'CALL THIS FIRST in a new session' is an explicit, front-loaded usage trigger, and 'without reading old chat transcripts' implies the alternative it replaces. There's no stated when-not condition or a named sibling to prefer in other cases, so a 4 rather than a 5.

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

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

With no annotations, the description carries the burden, and it does disclose the most important trait: this overwrites the prior checkpoint while preserving the timeline, which is a safe-guard against data loss. It stops short of stating auth requirements, storage location, or what the write 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?

Two short sentences, no filler, and the replace-semantics constraint is front-loaded before the routing advice. Every 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 13-parameter mutation tool with no annotations and no output schema, the description covers the essential overwrite behavior and the sequencing relative to siblings. It leaves a small gap around permissions/return behavior, but the rich schema covers the payload side.

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 92%, so the 13 parameters are already well documented in the schema (task, agent, notes, tests, blockers, keyFiles, etc.). The description adds no field-level meaning beyond what the schema provides, so the baseline 3 is correct.

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 ('Write a complete checkpoint for the project') and adds the crucial scope qualifier that it replaces the previous checkpoint while keeping the timeline. An agent can distinguish this full-write tool from the incremental siblings without opening a schema.

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 names the timing ('at the start of a new task') and routes the agent to the correct alternatives afterwards ('use update_handoff or log_progress'). This is exactly the when/when-not/alternative guidance the dimension asks for.

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 does disclose a genuinely important behavioral trait: plain fields replace stored values while append* lists merge without duplicates. It omits permission requirements, whether the handoff must already exist, and error/conflict behavior, so it is not fully 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, front-loaded with the core mutation semantics followed by the timing guidance. No filler; each sentence adds distinct value.

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 20-parameter mutation tool with no annotations and no output schema, the description covers the merge semantics and when to invoke it, which are the key agent questions. It does not address permissions, create-vs-update behavior, or failure modes, leaving minor gaps.

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

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

The schema covers 60% of the 20 parameters, and the description usefully explains the replace-vs-append* naming convention and the de-duplication behavior, which the schema does not state. It still leaves required params like projectPath/agent and several field semantics without added meaning in the description.

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

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

The description gives a specific verb and resource ("Change selected checkpoint fields" / handoff), clearly conveying a partial-update operation. However, it never distinguishes itself from close siblings like save_handoff, prepare_handoff, or resume_task, so an agent must infer the boundary on its own.

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

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

"Call before you stop, with verified progress, next steps and real test results" gives a concrete trigger and expected content, which is clear usage context. It stops short of naming when NOT to use it or pointing to save_handoff/prepare_handoff as alternatives, so the routing guidance is incomplete.

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