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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful context that the listing targets the remote gateway and reflects 'currently registered' agents, which is meaningful beyond the annotations, though it does not detail output shape or pagination.

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

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

The description is compact and well-structured: a one-line action, a use-when block, and a do-not-use block with a concrete alternative. Every sentence adds decision-relevant value, and the core action 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, read-only, optional-parameter list tool, the description is complete: it states the action, the intended use cases, the exclusion, and the fallback for the excluded case. No output schema is present, but the nature of a listing operation makes return expectations straightforward.

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 stackName parameter is fully documented in the schema itself. The description adds no parameter-specific guidance, but the baseline of 3 applies because the schema already carries the semantic weight.

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 a specific verb and resource: 'List agents currently registered on the remote OpenClaw gateway.' It clearly identifies what the tool does and differentiates it from sibling tools about stacks, status, config, and logs by focusing on agent registration.

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

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

The description explicitly states when to use the tool ('see which agents are running, debug agent routing, or count active workspaces') and when not to use it (one agent's logs), even providing the fallback command `clawops agents logs <name>`. This leaves no ambiguity for an agent deciding between tools.

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 provide destructiveHint=trueaint and idempotentHint=false, so the safety profile is partially covered. The description adds valuable behavioral context by labeling the operation 'Deterministic' and clarifying that the plan describes exactly what will be created, while also noting it is the agent-friendly path for deploy/destroy operations.

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

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

The description is compact, front-loaded with the core purpose, and uses short, scannable 'Use when' and 'Do NOT use when' sections. Every sentence earns its place with no redundancy or filler.

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

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

For a two-parameter tool with no output schemachers, the description covers the key context: when to use it, when not to use it, the deterministic behavior, and the relationship to plan generation. It doesn't spell out the return value or confirmation flow, but annotations and the schema cover the critical safety and parameter aspects.

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 both parameters are already fully documented in the schema. The description doesn't add syntax or additional meaning beyond pointing to the plan file and the concept of applying it, which is sufficient but not above the baseline.

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 ('Apply') and resource ('previously-generated Maker plan'), and explicitly links it to deploy-plan.schema.json. It also differentiates from clawops_plan by specifying 'previously-generated' and is clear about the deterministic nature of the action.

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

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

The description provides explicit 'Use when' and 'Do NOT use when' guidance, including the exact alternative (clawops_plan) and the condition that selects it ('no plan file'). This leaves no ambiguity for an agent deciding between tools.

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 cover the safety profile with readOnlyHint, idempotentHint, and destructiveHint false, so the description does not need to restate it. It adds useful context about the remote gateway and the full-dump behavior when key is omitted, but does not disclose return format or error behavior. This is adequate but not rich beyond the annotations.

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

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

The description is compact and well structured: one action sentence followed by clear use and non-use conditions. Every sentence earns its place, and the primary 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?

This is a simple read-only tool with two optional parameters, no output schema, and rich annotations. The schema plus description fully specify how to invoke it, and sibling routing is explicit. Nothing required for correct invocation 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%, with key and stackName already documented including the dot-path example and the default stack path. The tool description adds no extra parameter meaning, 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 uses a specific verb ('Read') and resource ('configuration value from the remote OpenClaw gateway'), and gives concrete inspection examples such as active model provider and enabled channels. This clearly distinguishes it from mutation siblings like clawops_config_set.

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

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

The description explicitly provides 'Use when' and 'Do NOT use when' conditions, naming clawops_config_set as the alternative for changing config. An agent can reliably decide between read and mutate operations without further inference.

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 set readOnlyHint=false, destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the mutation/safety profile is covered. The description adds genuine behavioral detail: optional gateway restart, the fact that the running gateway keeps the old value without restart, and the one-key-at-a-time auditability rule. It does not discuss failure modes or permissions, but nothing contradicts the annotations.

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

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

The description is three compact sentences plus two clear usage lines, with the core action and optional restart stated first and every sentence earning its place. There is no redundant repetition of the title or schema.

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 4-parameter mutation tool with full schema coverage and safety annotations, the description supplies the missing decision context: when to use it, which sibling to use instead, and the no-bulk-edit constraint. No output schema is present, but the write behavior and restart semantics are adequately specified, so an agent can invoke 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 coverage is 100%, with each parameter already documented (dotted key path, stringified JSON value, restart default/effect, stackName default). The description contributes context through example config areas, but the schema carries the parameter-semantic burden and the description does not add much beyond it.

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 ('Set') with a clear resource ('configuration value on the remote OpenClaw gateway') and a scope-limiting optional behavior (restart). It also names clawops_config_get as the reading alternative, so the tool's identity is not confused with siblings like clawops_config_unset or clawops_config_get.

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 when-to-use examples ('model provider, channel auth, gateway port') and an explicit when-not-to-use with the alternative tool ('reading config — use clawops_config_get'). It also prohibits bulk-edit usage, which is a concrete exclusion.

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 destructiveHint=true, readOnlyHint=false, and idempotentHint=true. The description adds genuinely useful context: the removal reverts to the OpenClaw default and, as implied by the restart parameter, does not affect the running gateway until a restart. No contradiction with annotations.

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

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

The description is tight and front-loaded: the core action and outcome come first, followed by structured use/don't-use guidance. Every sentence earns its place; no filler or redundant restatement of the title.

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 3-parameter mutation tool, the schema covers all parameters, annotations cover destructive/idempotent behavior, and the description supplies alternative routing. There is no output schema, so no return-value expectation exists. A minor gap is that the description does not explicitly flag irreversibility or failure modes, but overall it is 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 description coverage is 100%, so every parameter (key, restart, stackName) is already documented with meaningful descriptions. The tool description adds no parameter-level semantics beyond what the schema provides, warranting the baseline 3.

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

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

The description uses a specific verb ('Remove') and resource ('configuration key from the remote OpenClaw gateway config'), and spells out the result ('reverting it to the OpenClaw default'). This clearly distinguishes it from sibling tools like clawops_config_set and clawops_config_get without needing to inspect 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?

Explicit 'Use when' and 'Do NOT use when' sections give unambiguous routing criteria and name the exact alternative (clawops_config_set) for the contrasting case. An agent can decide with zero inference.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds context about what the validation actually checks (structural errors that would cause startup failure) and that it targets the remote gateway config. This is useful beyond annotations, though it doesn't detail the return format or whether it reports pass/fail. No contradictions with annotations.

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

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

The description is concise and well-structured: the first sentence states the core purpose, the second explains what it checks, and the third/fourth provide usage conditions. Every sentence earns its place, with no redundant information. It's front-loaded with the most important information and stays within a reasonable length.

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 validation tool with one optional parameter and readOnly/idempotent annotations, the description covers the essential context: what it does, what it checks, and when to use it. The only gap is that it doesn't describe the output format (e.g., pass/fail, error report). However, with no output schema and annotations indicating a safe operation, the agent likely needs to know the result format to interpret the response. Still, the description is largely complete for invocation decisions.

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 single parameter stackName is fully described in the schema (100% coverage), and the description adds no additional parameter details. Since the schema already explains the parameter and its default behavior, the baseline of 3 applies. The description does not add value here 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 the tool validates the OpenClaw gateway config against a known schema, checking for specific structural errors (wrong types, unknown top-level keys). It distinguishes itself from the config-changing sibling (clawops_config_set) by naming the alternative and its use case. The verb 'validate' and resource 'remote OpenClaw gateway config' are precise 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?

Explicit 'Use when' and 'Do NOT use when' sections give concrete scenarios: verifying config before restarting or after manual edits, and explicitly routing config changes to clawops_config_set. This is the gold standard for usage guidance – the agent knows exactly when to invoke this tool and when to choose a sibling.

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 destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds valuable specifics: triggers elicitation confirmation with a resource diff (R19), irreversibility ('Cannot be undone'), and the instruction to always confirm the stack name. It does not mention idempotency behavior (despite idempotentHint=true), but this is a minor omission.

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

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

The description is well-structured with clear sections: the core action and consequences, then 'Use when' and 'Do NOT use when' blocks. Every sentence carries meaning—there is no filler. The key warning about irreversibility is front-loaded, and the guidance is organized for quick parsing.

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 destructive action with no output schema, the description covers all essential context: what it does, when to use, when not to use, safety confirmations, and the irreversibility. It also addresses common pitfalls (confusing with gateway restart, unsure stack). Nothing critical is missing for an agent to invoke 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 coverage is 100% – both 'stackName' and 'yes' have descriptions in the schema. The tool description adds a reiteration that stackName is 'worth repeating back to the user' due to destructiveness, but this is largely a reinforcement of the schema's warning rather than new meaning. Given the baseline of 3 for high coverage, this 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 states a specific verb ('Destroy') and resource ('a clawops stack'), and explicitly notes it 'Removes ALL provisioned resources,' making the purpose unambiguous. It also differentiates from siblings by warning against using it for gateway stop, reinforcing that it is exclusively for destruction.

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

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

The description provides explicit 'Use when' conditions (user asks to destroy/tear down/delete/remove) and 'Do NOT use when' conditions (temporary gateway stop, uncertainty about stack), naming alternatives like clawops_gateway_restart and clawops_stacks_list. This is exemplary guidance for tool 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?

Beyond annotations that declare read-only and idempotent hints, the description states 'it changes nothing, and never runs `openclaw doctor --fix`,' reinforcing the non-destructive behavior. It also explains the status semantics (fail/warn/info) and the meaning of `ok`, which is crucial for interpreting the report, and discloses that with `stackName` it contacts the host remotely.

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 organized into three distinct paragraphs: scope, usage criteria, and output semantics. Every sentence adds necessary information (what, when, when not, what it changes, how to read results) without fluff, and it is front-loaded with the core diagnostic purpose.

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

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

The tool has no required parameters and no output schema, so the description carries the burden of explaining returns. It lists all check categories, describes the status values, and clarifies the meaning of `ok` and warnings, giving an agent enough context to invoke the tool and interpret results. The usage restrictions and behavioral notes fill gaps that annotations alone would not cover.

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?

While the schema already documents both parameters with 100% coverage, the description adds semantic detail by listing the additional remote checks triggered by `stackName` (container state, deployed version, gateway probe, port exposure, disk usage, log rotation, hardening drift) and explains the status categories that `failuresOnly` filters on. This enriches the meaning beyond the schema's brief descriptions.

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: 'Run clawops's diagnostics and return the report,' then enumerates the exact checks performed (Node/Pulumi runtime, config, SSH key, cloud credentials, etc.). It clearly differentiates from siblings by framing itself as the 'do not know what's wrong' diagnostic tool, distinct from `clawops_status`, `clawops_harden`, or `clawops_monitor`.

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 includes explicit 'Use when' and 'Do NOT use when' sections, giving the agent clear decision criteria: use it for unknown problems, before deploy/upgrade/migration, or to discover the actual gateway version. It explicitly says not to use when the problem is already known and wants a fix, and it points out that no tool repairs a gateway, directing the user to CLI commands instead.

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

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

The description adds valuable context beyond annotations: 'it affects every agent on the host' and 'Brief downtime (~10s).' Annotations already signal destructive and non-read-only, but the specific scope and duration are new behavioral disclosures. It also highlights the version-specific limitation (OpenClaw 2.0), which helps set expectations.

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 composed of three short sentences, each carrying necessary information: the action, the trigger conditions, and the global impact/downtime. There is no fluff, but it could be slightly tightened; however, 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?

For a tool with a single optional parameter and no output schema, the description adequately covers the purpose, when to use it, impact scope, and downtime. It doesn't explicitly mention how to confirm the restart succeeded (e.g., via clawops_status), but that is a minor omission for such a simple restart operation.

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 already provides a full description of stackName, including the default-stack behavior when omitted. The tool description does not add any extra meaning to the parameter, so the baseline 3 for high schema coverage 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 opens with a specific verb and resource: 'Restart the OpenClaw gateway daemon on the remote instance.' This clearly distinguishes it from sibling tools like clawops_up or clawops_apply, which are about deployment/configuration rather than restarting. The 'Use when' clause further reinforces the intended purpose.

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 explicit trigger conditions: 'gateway-wide config change requires reload' or 'gateway is reported as unresponsive.' It also notes that per-agent restart is unavailable, ruling out that alternative. However, it doesn't name another sibling tool to use for different scenarios, only states that this is the only restart available.

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?

Goes far beyond the annotations. It discloses the rollback/failure path for tailscale: true ('If that fails, nothing is recorded and the public address stays in use'), the refusal behavior for tailscaleRevert on private-only stacks, that it 'does not change firewall rules', and that the auth key is never passed through the tool (R6). Consistent with readOnlyHint=false and destructiveHint=true — no contradiction.

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 core purpose is front-loaded in the first sentence, and the paragraphs are logically grouped (usage triggers, tailscale, revert, exclusions). It is long, but the Tailscale integration is genuinely intricate and every sentence earns its place — 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?

Comprehensive for a 6-param, security-sensitive tool: covers scope, when-to-use, failure modes, reversals, and non-goals (firewall, health checks). There is no output schema, and the description doesn't spell out the return format, but it does reference 'the hardening report' under dryRun. Minor gap only.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds genuine value beyond the schema for tailscale and tailscaleRevert (host-key pinning, failure semantics, private-only refusal), pushing it to a 4. The yes, options, and stackName params are fully covered by 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?

Opens with a specific verb-resource pair ('Apply security hardening to a deployed stack') and enumerates concrete modules (SSH, UFW, fail2ban, unattended-upgrades, Docker socket, per-cloud checks). It also names the sibling it is not ('that is clawops_doctor'), so an agent can disambiguate without opening the 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?

Gives explicit 'Use when' triggers (harden/secure/lock down, ask for the hardening report, put a stack on the tailnet) and explicit 'Do NOT use when' exclusions (health checks → clawops_doctor), plus a hard constraint ('Do NOT pass tailscale and tailscaleRevert together'). Nothing is left to inference.

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 description adds substantial behavior beyond annotations: SSH key pair generation, additive safety of stacks, the force:true overwrite path orphaning Pulumi state, credential handling from environment, and provider-specific bucket naming behavior. The annotations only say read-only/destructive/idempotent flags, so this context is genuinely valuable and consistent.

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

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

The description is longer than average, but every sentence carries operational information: safety, prerequisites, provider nuances, and routing to the right sibling. It is front-loaded with the core purpose and organized into scannable paragraphs.

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 8-parameter initialization tool with no output schema, the description covers purpose, safety, prerequisites, provider-specific parameter rules, exclusions, and sibling routing. An agent has everything it needs to decide when to call it and how to configure 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 coverage is 100%, so the baseline is 3. The description adds inter-parameter meaning beyond the schema: omitting stateUrl makes clawops derive a bucket needing credentials, local requires host instead of cloud account, and force:true is tied to the state-backend orphaning warning. This is a clear improvement over 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?

The description opens with a specific verb and resource: 'Register a stack and write ~/.clawops/config.json', and names exactly what it creates. It clearly distinguishes itself from deployment tools by stating 'Nothing is provisioned and nothing is charged; this only creates local configuration.'

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 use conditions: when no config exists, when adding a second stack, or on a fresh machine. It also names an exclusion and alternative: 'Do NOT use when: the user wants to deploy — that is clawops_up, after this.'

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 mark the tool as readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds useful behavioral context by clarifying this is not real-time streaming and that output is trimmed to 8KB regardless of requested line count.

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 opening sentence states the core purpose, followed by tightly organized 'Use when' and 'Do NOT use when' sections. Every sentence is decision-relevant and there is no filler or repetition.

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

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

For a read-only log tool with three optional parameters, the description provides all needed context: what resource it targets, what cases are out of scope, and how users can accomplish those out-of-scope tasks. The output trimming behavior is also disclosed, which is sufficient given the simple log-return expectation.

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 parameters are already well documented in the schema and the tool description does not need to compensate. The description adds a small caveat about keeping tailLines small, but it does not add significant meaning beyond the structured 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 uses a specific verb and resource: 'Tail recent gateway logs from a clawops-managed instance.' It clearly distinguishes this from instance-level system logs and real-time streaming, and none of the sibling tools cover log tailing, so an agent can identify its role.

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 'Use when' conditions ('investigate recent activity or errors') and explicit 'Do NOT use when' conditions with concrete alternatives: suggest `clawops logs -f` for streaming and `clawops ssh --command 'journalctl ...'` for system logs. This is model behavior for routing.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful non-schema behavior: it is a live snapshot rather than streaming, it is scoped to a running stack, and it is richer than clawops_status. This meaningfully supplements the annotations without contradicting 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?

The description is tightly scoped and front-loads the core action and contents, then provides crisp usage guidance. Every sentence earns its place, and the Do NOT use section prevents misuse without unnecessary elaboration.

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 read-only snapshot tool with two optional, fully documented parameters, the description covers invocation scope, output contents, relationship to siblings, and exclusion cases. It is complete enough for an agent to select and call the tool correctly without additional 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?

Schema description coverage is 100%, with both parameters already documented (stackName defaults to active stack; tailLines defaults to 5). The description's mention of 'recent log lines' aligns with tailLines but does not add parameter-level depth beyond the schema. Baseline 3 is appropriate when the schema carries the semantic load.

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 ('Take a live snapshot') and resource ('running clawops stack'), and enumerates exactly what it covers: gateway health, container status, resource usage, and recent log lines. It also differentiates itself from clawops_status by positioning itself as a richer health overview.

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

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

The description provides explicit 'Use when' conditions and explicit 'Do NOT use when' exclusions with named alternatives (clawops_logs_tail, clawops_config_get). An agent can unambiguously select this tool versus siblings based on stated user intent.

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, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavior beyond that: 'does NOT apply', output is JSON conforming to an external schema, and the artifact is meant for review before application. It does not disclose minor operational details like auth requirements, but those are less critical for a read-only plan tool.

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

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

The description is compact, front-loaded with the core purpose, and each sentence earns its place. The 'Use when' and 'Do NOT use when' structure is scannable and gives the agent direct decision rules without 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?

For a 10-optional-parameter planning tool, the schema covers all parameters and the description covers output format ('JSON conforming to deploy-plan.schema.json') and the decision boundary for when to use it. It is slightly less self-contained because the referenced schema is not inline, and the distinction between clawops_up and clawops_apply is not elaborated, but nothing essential is missing for correct selection and 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 100%, and every parameter already has a detailed description, including defaults, omitted behavior, and refusal cases. The tool description itself does not add parameter-level meaning, so the baseline score of 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 uses a specific verb and resource: 'Generate a Maker deploy plan' and immediately clarifies the key distinction that it 'does NOT apply'. This differentiates it from apply/up siblings without requiring the agent to inspect any other tool.

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

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

It explicitly states when to use it ('when the user wants to see what would be created before committing') and when not to use it ('user has explicitly asked to deploy... go directly to clawops_up'). This is model guidance with a named alternative.

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 convey readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds behavioral scope: it enumerates managed stacks across all configured providers and has no filtering. It doesn't describe output format or pagination, but for a read-only list with zero parameters that is a minor 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 compact and front-loaded: one sentence states what the tool does, followed by expanded use-when and do-not-use guidance. Every sentence earns its place, and 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 zero-parameter, read-only, non-destructive list tool with no output schema, the description is complete. It tells the agent what the tool returns at a conceptual level ('overview of deployments'), when to use it, and which sibling to route to when a specific stack is named. No critical context is missing.

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

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

There are zero parameters and schema description coverage is 100%, so the schema already fully covers this dimension. The description reinforces the no-parameter, unfiltered nature by saying 'all' stacks 'across all configured providers,' which helps an agent understand that no arguments are 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 opens with a specific verb and resource: 'List all clawops-managed stacks across all configured providers.' It also differentiates itself from the sibling clawops_status by explicitly saying that a named specific stack should go to clawops_status instead. This gives an agent a precise, unambiguous purpose.

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

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

The description explicitly says when to use the tool ('user wants an overview of their deployments', 'what stacks do I have', 'compare stacks before an operation') and when not to use it ('user named a specific stack'), and names the alternative tool (clawops_status). This satisfies the when/when-not/alternatives requirement fully.

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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context beyond annotations: 'Reads stack outputs; does not contact the host,' which clarifies why this is not suitable for liveness checks. It also discloses the possible empty result ('nothing is deployed yet').

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

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

The description is front-loaded with the core purpose, then gives crisp usage boundaries. Every sentence earns its place, and the use/do-not-use sections are structured for quick agent scanning.

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 single-optional-parameter read-only tool with no output schema, the description provides enough to select and invoke correctly: what it returns, what it does not do, and when to choose an alternative. Nothing critical 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%: the only parameter, stackName, is fully described in the schema including the default behavior. The description adds no additional parameter details, so the baseline of 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 uses a specific verb ('Get') with a clear resource ('what is deployed for a clawops-managed stack') and enumerates concrete outputs: public IP, gateway URL, SSH user, or nothing deployed. It also distinguishes itself from siblings by explicitly noting it reads stack outputs and does not contact the host.

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 an explicit 'Use when' clause and a 'Do NOT use when' clause with named alternatives (clawops_doctor, clawops_logs_tail, clawops_config_get). This gives an agent unambiguous routing guidance for selecting this tool over 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that it's a polling mechanism 'Per R12 streaming model' and clarifies it checks progress/completion. This goes slightly beyond annotations, though it doesn't detail polling intervals or response format.

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

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

The description is concise and well-structured, with purpose stated first and usage conditions clearly separated. Every sentence earns its place; there is no redundancy or padding.

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 poll tool with one parameter and annotations covering safety, the description provides usage context, prerequisites, and the type of task. It mentions the streaming model but doesn't describe the return format; however, the agent can infer it returns status. This is adequate for correct invocation.

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

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

Schema coverage is 100% — the taskId parameter is fully described as the ID returned by long-running tools. The description reinforces this but doesn't add new meaning beyond the schema. With full schema coverage, the baseline of 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 states a specific verb ('Poll') and resource ('long-running clawops task'), and names the exact tools (clawops_up, clawops_destroy, clawops_apply) that return the taskId. This clearly differentiates it from siblings like clawops_status (which likely reports overall system state) and other list tools.

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

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

It provides explicit 'Use when' conditions (user waiting on a long-running deploy/destroy, or checking if an operation finished) and a 'Do NOT use when' condition (no active taskId — start the operation first). This leaves no ambiguity about when to invoke it versus starting a new operation.

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

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

Annotations already provide idempotentHint and destructiveHint, but the description adds concrete behavior: idempotency detail ('no diff'), long-running timing (median 3min, p99 8min), and progress notifications. This is valuable context beyond the annotations, though it does not explicitly describe side effects on spec changes.

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

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

The description is well-structured and front-loaded: core function first, then idempotency and timing, then usage guidance. Every sentence adds value, and it is not verbose despite covering multiple aspects.

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 9-parameter provisioning tool with no output schema, the description covers usage, alternatives, timing, and idempotency. It does not describe the return value, but given the lack of output schema and the presence of progress notifications, this is acceptable and likely sufficient for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all 9 parameters. The description does not add parameter-specific meaning beyond referencing plan usage; it meets the baseline but does not elevate it.

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 ('Provision and deploy a clawops stack') and differentiates from siblings by explicitly naming clawops_plan for planning and refresh for updates. It is unambiguous about what this tool does versus alternatives.

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 explicit 'Use when' and 'Do NOT use when' conditions, naming alternatives (clawops_plan, refresh) and the decision criteria (explicit deploy request, plan reviewed, exploratory mode). This is exemplary 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?

The description adds valuable context beyond the annotations: it reveals the internal sequencing ('plan → user confirms (elicitation) → up → wait for healthy → return URL') and the completion condition. It does not explicitly discuss destructive side effects, but the annotations already carry destructiveHint: true, so the description is not misleading and the annotations cover that risk.

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 tightly structured: the workflow is front-loaded in the first sentence, followed by crisp use-case and exclusion rules. There is no filler or repetition of schema content, and every sentence earns its place.

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

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

For a complex workflow tool with no output schema, the description covers the overall lifecycle, user confirmation requirement, health verification, and the returned URL. It leaves minor gaps around failure behavior and output formatting, but these are secondary given the schema and annotations already cover parameter defaults and safety signals.

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 documents all four parameters clearly with defaults, enums, and provider-specific spelling notes. The description adds no new parameter-level detail, which is acceptable given the schema already carries the semantic load; a 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 verb ('deploy OpenClaw') and a clear scope: an end-to-end workflow from intent to a 'verified, healthy gateway.' It also distinguishes itself from siblings by calling out that it is a 'Single-tool workflow' and explicitly marking 'clawops_apply' as the one-step alternative, so an agent can identify it 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?

The description gives explicit 'Use when' and 'Do NOT use when' guidance with concrete user phrasing examples ('deploy to AWS', 'spin up an OpenClaw on GCP for me'). It names the alternative tool (clawops_apply) and excludes destroy/update cases, leaving no ambiguity about when to select this workflow.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is established. The description adds meaningful behavioral detail by listing the internal steps and the output format, showing that the tool reads logs and service status rather than mutating state. It does not explain partial-failure behavior or permission requirements, but this is not a major gap given the annotations.

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

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

The description is compact and front-loaded: the core purpose and internal workflow come first, followed by crisp use and do-not-use conditions. Every sentence contributes; there is no filler or redundant restating of the tool name.

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

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

For a tool with one optional parameter and no output schema, the description covers the essential context: when to trigger it, what steps it performs, what it returns, and when to avoid it. The only remaining parameter detail is already captured by the 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?

The schema covers 100% of the parameter documentation: stackName is described as 'Which stack to diagnose' with a clear default behavior. The description adds no parameter-specific detail beyond the context of diagnosing a stack, so the baseline of 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 identifies the tool as a diagnostic workflow for an unhealthy stack and details its internal pipeline: status check, gateway logs, agent logs, systemd service status, then a structured diagnostic report with remediation. This multi-step framing distinguishes it from simpler sibling tools like clawops_status or clawops_logs_tail, so the agent knows this is a diagnostic entry point, not a single-status command.

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 'Use when' and 'Do NOT use when' conditions: it is the best entry point when a 'not working' symptom is reported without a known cause, and it should not be used when a specific fix is already requested. It stops just short of naming the alternative sibling tools that would handle those specific cases, so it provides clear context but not complete routing.

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