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

With no annotations, the description fully conveys the read-only behavior of listing, flagging, and recommending. It does not mention permissions or rate limits but is sufficient for a safe 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?

A single sentence efficiently conveys three key actions (list, flag, recommend) without extraneous words. It is well-structured and 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?

Given zero parameters and no output schema, the description provides a complete picture of what the tool does. It could mention output format but is sufficiently detailed for an agent.

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 no parameters (0 params), so the baseline is 4. The description adds no parameter information, which is unnecessary given no parameters.

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 three specific actions: listing newer versions, flagging CRITICAL regressions, and recommending a version. This distinguishes it from siblings like current_version (shows current) and regression_catalog (lists regressions).

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 usage for checking upgrade options but does not explicitly state when not to use it or mention alternatives. It is clear but lacks exclusions.

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

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

No annotations are provided, so the description must cover behavioral traits. It correctly implies a read-only operation (returning info, no side effects). However, it does not disclose whether authentication is needed or any preconditions, though for a simple version check this is minimal.

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, front-loaded with the core purpose. Every word adds value: the first sentence states the function, the second gives usage advice. No wasted text.

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

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

Given no output schema, the description partially explains what is returned ('version + how it was detected') but lacks exact format details. For a simple diagnostic tool in a context with upgrade-related siblings, it covers the essential purpose but could be more explicit about the return structure.

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 zero parameters, and the description adds no parameter-level information. With schema coverage at 100% and no parameters, the baseline of 4 is appropriate; the description does not need to add param details.

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 what the tool does: return the installed OpenClaw version and detection method. It provides a specific verb-object pair ('Return the currently-installed OpenClaw version') and adds context about detection. However, it does not explicitly differentiate from sibling tools beyond implying it's the first step.

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 clear usage context: 'Run this first to confirm the backend can read your deployment.' This implies it should be used before other operations, but it does not provide when-not-to-use or mention alternative tools for version-related queries.

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

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

With no annotations, the description carries the full burden. It states the tool lists data, implying a read-only operation, but does not disclose potential pagination, performance impact, or whether the list is complete. Minimal but not misleading.

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

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

The description is a single concise sentence that conveys everything needed: the action, object, and output fields. No extraneous words.

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 has no parameters and no output schema, the description covers the return fields and purpose adequately. It could mention if there is any filtering or ordering, but for a simple list tool it is mostly complete.

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

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

There are no parameters, so parameter semantics are trivial. The description does not need to elaborate on parameters, and the schema coverage is 100%. 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 the tool lists all stored snapshots and enumerates the fields returned (id, captured_at, version, summary). It effectively distinguishes from sibling tools which are upgrade-specific actions.

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 tool is for viewing snapshots but provides no explicit guidance on when to use it versus siblings like pre_upgrade_snapshot or regression_catalog. Usage context is only implied.

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 describes the output (surfacing failures, recovered, unchanged) and outcomes, but does not disclose if the tool modifies state (e.g., creates a snapshot) or if there are side effects. The phrasing 'Take a fresh post-upgrade snapshot' suggests a possible mutation, but it is ambiguous.

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 sentences: first states the action, second lists what is surfaced, third defines outcomes. No redundant information, and each sentence earns its place.

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

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

The description covers the key outputs and outcomes, and with only one well-documented parameter, it is fairly complete. However, it does not explain the format of the returned data or explicitly state the prerequisite of having a pre-upgrade snapshot, though this is 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?

The only parameter (pre_snapshot_id) has 100% schema coverage, but the description adds value by specifying it is 'the snapshot_id returned by pre_upgrade_snapshot', which clarifies its origin beyond the schema 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 clearly states what the tool does: takes a fresh post-upgrade snapshot and diffs against a pre-upgrade snapshot, surfacing new failures, recovered checks, and unchanged failures. It also defines the outcome categories (success/degraded/regressed). This distinguishes it from siblings like pre_upgrade_snapshot.

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 usage is after an upgrade and after a pre_upgrade_snapshot has been taken. It is clear about the context but does not explicitly state when not to use it or mention alternatives like regression_catalog.

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 carries full burden. It implies running checks and persisting a snapshot, but does not explicitly state if this is a read-only or destructive operation. Returns snapshot_id, which is helpful.

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, front-loaded with action, no filler. Every sentence adds 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?

Given the tool's simplicity (one optional param, no output schema), the description is complete. It covers purpose, output, and usage with sibling tools.

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

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

Schema coverage is 100% for the single optional parameter. Description adds meaning by explaining target_version is stored in the snapshot, going beyond the schema's 'Optional — version'.

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 uses specific verb 'Run every detection check' and resource 'Snapshot', clearly distinguishing from siblings like post_upgrade_verify and rollback_guide.

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?

States that the snapshot_id is used for post_upgrade_verify and rollback_guide, giving clear context for when to use this tool. Does not explicitly mention when not to use it, but the guidance is strong.

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 must carry the full burden. It discloses that the tool returns a list of regression entries with structured fields, implying a read-only query. However, it does not explicitly state that no data is modified or mention any other behavioral constraints (e.g., rate limits, authentication needs).

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

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

The description is two sentences long, with the first sentence delivering the core purpose. The second sentence lists the output fields, which is helpful though slightly verbose. No extraneous 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?

Given the tool's simplicity (0 required parameters, no output schema), the description is sufficient. It explains both input and output behavior. Minor gap: it does not specify behavior when no regressions match the filter or when the catalog is empty, but this is acceptable for a low-complexity 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% for the single parameter, and the description reinforces its optional nature ('optionally filtered to a specific version'). Additionally, the description lists the exact fields of each entry (id, version range, severity, description, mitigation, linked field reports), which adds meaning beyond the schema's parameter documentation.

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

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

The description begins with 'Return every known regression in the catalog,' which is a specific verb+resource combination. It optionally filters by version and enumerates the entry fields (id, version range, severity, etc.), distinguishing it from sibling tools like 'available_upgrades' or 'rollback_guide'.

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

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

The description clearly states the tool returns regressions, optionally filtered by version. While it doesn't explicitly say when not to use it, the sibling tool names (all upgrade or snapshot related) make the usage context clear. No contradictions or misleading guidance.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool produces a plan including risk notes, but does not explain if it modifies state, requires permissions, or any side effects beyond composition.

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 efficiently conveys purpose and contents. No redundant words, and key information is front-loaded.

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

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

The description adequately explains what the plan contains, but lacks details on output format (text/structured) or any prerequisites beyond the snapshot_id. For a simple tool with one parameter, this is nearly 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?

The input schema describes 'snapshot_id' as 'Pre-upgrade snapshot to roll back to'. The description adds context by specifying 'pre-upgrade snapshot' and 'roll back plan', reinforcing the parameter's role. With 100% schema coverage, the description adds value beyond the schema.

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

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

The description clearly states it composes a rollback plan for a pre-upgrade snapshot, listing specific components (downgrade command, state-restore steps, risk notes). This distinguishes it from siblings like upgrade_guide (upgrade planning) and list_snapshots (listing snapshots).

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 usage when needing a rollback plan for a snapshot, but does not explicitly state when to use this tool vs alternatives, nor does it provide exclusions or cross-references to 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?

No annotations are provided, so the description carries full burden. It discloses key behavioral traits: the tool composes a plan covering prep, upgrade, verification, rollback, and known regressions. However, it does not mention whether any state is modified, auth requirements, or rate limits.

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

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

The description is two sentences with no waste. It front-loads the main action and then lists contents. 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?

Given only one parameter and no output schema, the description is sufficiently complete. It covers all relevant aspects of the tool's output and inputs. Missing details about return format are not critical.

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% for the single parameter 'target_version', which includes an example. The description adds no additional meaning 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 clearly states 'Compose the step-by-step upgrade plan' with a specific verb and resource. It enumerates included sections (prep, upgrade, verification, rollback, regressions) and distinguishes from sibling tools like rollback_guide and post_upgrade_verify.

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 this is the primary tool for an upgrade plan, but it does not explicitly state when to use it versus alternatives or when not to use it. No exclusion criteria or alternative tool references are provided.

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