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

The description discloses ordering (newest first), content (dry-run and execute), and filter capability (by one node). Although no annotations exist, the description effectively communicates the tool's read-only nature and output characteristics.

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 extremely concise with two front-loaded sentences providing essential information without unnecessary 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?

For a simple query tool, the description covers the key aspects: content, ordering, and filtering. The presence of an output schema reduces the need to describe return format, but the limit parameter is not explained, leaving a minor gap.

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

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

Schema coverage is 0%, so the description must compensate. It explains the 'name' parameter as a node filter but does not mention the 'limit' parameter. This is partial coverage, but the baseline for 0 params would be 4; here there are 2 params and only one is described.

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 provides recent audit entries (dry-run and execute), newest first, with optional name filtering. It is distinct from sibling tools like fleet_status or node_detail, which serve different purposes.

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

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

The description implies use for retrieving recent audit logs, optionally for a specific node. However, it does not explicitly state when to use this tool versus alternatives or provide prerequisites or 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?

Despite no annotations, the description discloses key behaviors: dry-run mode, idempotence on confirm, audit logging, and lifecycle timing. Lacks details on error handling or state if already installed, but sufficient for typical use.

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 the main action; no wasted words. Efficiently conveys necessary information.

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

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

Given the tool's simplicity (2 params) and an existing output schema, the description covers purpose, usage, preconditions, and safety (dry-run, idempotence). Leaves room for parameter format details but is largely 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?

The description explains the 'confirm' parameter (dry-run vs run) and implies 'builder' identifies the host. However, does not specify format or validation for 'builder' (e.g., hostname vs IP). Schema has 0% coverage, so description partly compensates but leaves ambiguity.

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 verb ('Install') and resource ('build toolchain + deps on a builder host') and distinguishes from siblings like 'provision' or 'upgrade' which handle higher-level operations.

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

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

Provides clear guidance: dry-run by default, confirm=true to run idempotently, records to audit log, and run once per builder before first upgrade/provision. Does not explicitly exclude alternative tools but context is sufficient.

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

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

With no annotations provided, the description effectively discloses key behaviors: dry-run mode, confirmation flag, last-member protection, and audit logging. It lacks details on prerequisites or reversibility, but covers the most critical aspects.

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 extremely concise with two sentences that convey all essential information. Every word adds value, and critical points are 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?

Despite an output schema existing, the description does not mention what the tool returns. It also lacks explanation of the 'record' parameter and fails to describe the outcome of the operation beyond the action itself. For a tool with three parameters, the description is incomplete.

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

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

Schema description coverage is 0%, and the description only implicitly references the 'confirm' parameter. The required 'name' parameter and optional 'record' parameter are not explained, leaving agents with insufficient information to set parameters correctly.

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

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

The description clearly states the action: 'Manually pull a node from its DNS pool(s).' It is specific about the resource (DNS pool) and distinguishes from sibling tools like dns_pool_restore and dns_pool_status.

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

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

The description provides basic usage guidance: 'Dry-run unless confirm=true' and 'Refuses to empty a pool (last-member protection).' However, it does not explicitly state when to use this tool versus alternatives like automated ejection or pool status checks.

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 the dry-run behavior (default false), the confirm flag for execution, and that the action is audited. This is sufficient for a simple operational tool, though more detail on permissions or side effects could improve it.

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 extremely concise: two sentences with no wasted words. The key action and critical behavior (dry-run/confirm) are front-loaded, making it easy to parse.

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 3 parameters and an output schema (not shown), the description does not mention return values or prerequisites (e.g., node must be ejected). It covers the core behavior but lacks completeness for an agent to use it without additional context.

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 has 3 parameters with 0% description coverage, so the description must compensate. It explains the confirm parameter's role (dry-run vs. execute), but does not clarify 'name' or 'record'. These parameters remain ambiguous, leaving the agent guessing their purpose.

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 'add a node back to its DNS pool(s)', which specifies the verb (add) and resource (DNS pool). It distinguishes from sibling tools like dns_pool_eject (removal) and dns_pool_status (status).

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

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

The description implies usage for restoration after ejection or failure, and explains the dry-run behavior with confirm flag. However, it does not explicitly state when not to use or provide alternatives, leaving some ambiguity.

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

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

With no annotations provided, the description must disclose behavioral traits. It does state 'Read-only', which is key, but lacks details on authorization needs, rate limits, or what happens during partial failures. The mapping behavior is implied but not fully elaborated.

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 extremely concise with two front-loaded sentences. The first sentence states the core function, and the second adds the 'read-only' trait. No unnecessary words or redundancy.

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

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

While an output schema exists and reduces the need to describe return values, the description falls short on parameter semantics. It does not clarify the role of 'record', which is the sole parameter. Considering the tool's simplicity, this omission makes it incomplete for effective use.

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 one parameter ('record') with no description and 0% schema coverage. The tool description does not explain the parameter's purpose, valid values, or effect on the output. Since schema coverage is low, the description should compensate, but it fails to do so.

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 shows 'current members of each managed DNS pool, mapped back to node names', which is a specific verb-resource combination. It also declares 'Read-only', distinguishing it from action-oriented siblings like dns_pool_eject and dns_pool_restore.

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 read-only usage but does not explicitly state when to use this tool over alternatives. It lacks guidance on when not to use it or any prerequisites. The 'Read-only' tag gives a hint, but no direct comparisons to sibling tools are provided.

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

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

No annotation provided, so the description must disclose behavioral traits. It only lists output fields but does not state whether the tool is read-only, requires authentication, or has rate limits. The read-only nature is implied but not explicit.

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

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

The description is one sentence that efficiently conveys the tool's purpose and output. It is front-loaded with 'Health of every node in the fleet' and includes the key metrics.

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 an output schema exists, the description adequately covers what the tool returns. It is complete for a simple status overview 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?

There are no parameters, so the description adds no additional meaning beyond the schema. Baseline for zero parameters is 4, indicating no deficiency.

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 provides health metrics of all nodes grouped by cluster, listing specific fields like reachability, getHealth, version, etc. It distinguishes itself from siblings like 'node_detail' by being aggregated fleet-wide.

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

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

No guidance on when to use this tool versus alternatives. For example, it does not mention that for a single node's details, one should use 'node_detail' 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?

Discloses 'Read-only' and describes behavior (no leader slot within min_window_minutes). Without annotations, more detail (e.g., pagination, rate limits) would improve transparency.

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 key info, no wasted 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?

Covers purpose and one parameter, but lacks explanation of 'name' parameter and output format. Given output schema exists, more context on return values would help.

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 0%, but description only explains 'min_window_minutes' partially. 'name' parameter is not explained (assumed validator identity), leaving ambiguity. For 2 parameters, insufficient.

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?

Clear verb 'Upcoming' and specific resource 'leader slots for a validator', with explicit purpose 'whether it's safe to restart now'. Distinguishes from sibling tools like 'restart' and 'node_detail'.

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 it 'helps plan restarts/upgrades without skipping your own slots', implying when to use. Lacks explicit when-not or alternatives, but clear enough for context.

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

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

No annotations are present, so the description must disclose behavioral traits. It describes the output as a 'full probe result' but omits details like read-only nature, rate limits, or side effects, leaving significant ambiguity for a mutation-free 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 two sentences and quickly conveys the core purpose. However, it could be structured to separate purpose from output details for better readability.

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

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

Given the presence of an output schema (not shown) and moderate tool complexity, the description lacks essential context such as error cases, required permissions, or what 'cluster reference data' entails, leaving the agent underinformed.

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

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

Schema description coverage is 0%, yet the description provides no additional meaning for the 'name' parameter beyond the fact that it identifies a node. No format, examples, or constraints are given.

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 returns a 'full probe result for a single node by name', including cluster reference data. However, it doesn't differentiate from sibling tools like fleet_status or bootstrap_builder_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?

No guidance is provided on when to use this tool versus alternatives, nor any prerequisites or exclusions. The context signals include many sibling tools but no comparison.

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

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

With no annotations provided, the description carries the full burden. It explicitly states the tool is read-only, produces ordered steps and policy preflight, and changes nothing. It also mentions using artifacts from the dedicated builder. Missing are potential preconditions or error states, but the description is fairly transparent for a 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 consists of two sentences that are entirely relevant. The first sentence states the purpose and the second emphasizes the read-only nature. It is concise, front-loaded, and contains no wasted 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?

The tool has an output schema (not shown) which likely describes return values, so the description does not need to elaborate. It covers the key aspects: what the tool does, what it produces, and that it is non-destructive. It does not mention preconditions or error scenarios, but these may be covered elsewhere.

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 has 0% description coverage, so the description must add meaning. It mentions 'target_version' in context, but does not explain the 'name' parameter clearly (node name? cluster name?). The description adds some value but does not fully compensate for the lack of schema 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 clearly states the verb 'plan', the resource 'node upgrade', and the scope 'dry-run' and 'read-only'. It distinguishes from the sibling 'upgrade' by specifying it is a planning step that produces ordered steps and policy preflight, and does not change anything.

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 indicates when to use: to preview upgrade steps before executing. It explicitly states 'Read-only' and 'changes nothing', providing clear context. However, it does not explicitly mention alternatives or when not to use, though the sibling list implies the distinction.

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

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

With no annotations, the description carries full burden and discloses key behaviors: default dry-run, execution gate, disk formatting requirement (format_devices), key creation caveat (solfleet never creates keys), and catch-up timeout. No contradictions.

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, front-loaded with purpose. The first sentence lists steps (slightly verbose but informative), the second explains parameters. It is efficient, though could be trimmed slightly.

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 5 parameters, no nested objects, output schema exists, and 14 sibling tools, the description covers dry-run, execution, disk formatting, key creation, and timeout. It does not miss critical behavioral context for safe 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 0%, so description must compensate. It explains confirm, format_devices, and catchup_timeout_s with context (default, purpose, constraints). Name and version are not explained but are self-evident. Overall, the description adds meaning beyond schema for 3 of 5 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 the verb 'Bring up' and the resource 'bare host into a serving node', listing specific steps (preflight, user, system tuning, etc.). It distinguishes from siblings like bootstrap_builder_host or upgrade by focusing on the full provisioning lifecycle.

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 explains the dry-run default and execution with confirm=true, and mentions gating by preflight/policy/audit. However, it does not explicitly state when to use this tool vs alternatives like bootstrap_builder_host or upgrade, which are present in sibling 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?

With no annotations provided, the description fully covers behavioral traits: it waits for catch-up, defaults to a dry-run, requires confirm=true to execute, is gated by policy, recorded in audit log, and never touches keys. It also differentiates behavior for RPC nodes vs voting validators.

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 sentences, each adding essential information. It is front-loaded with the primary action, then specifies behavior for node types and dry-run/confirm flow. 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's complexity (two node types, dry-run vs execution, policy gating, audit logging) and the presence of an output schema, the description covers all necessary aspects: what it does, how it behaves, parameter semantics, and safety guarantees. It is fully complete.

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

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

Schema description coverage is 0%, so the description must add meaning. It explains that 'name' is the node to restart, and 'confirm' defaults to false, enabling a dry-run that returns the plan and policy preflight. This clarifies the parameters' roles 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 restarts a node and waits for catch-up, distinguishing between RPC nodes and voting validators with different methods. It also explains the dry-run default versus actual restart with confirm=true. This is specific and distinguishes it from other 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?

The description explains when to use the tool (restarting nodes), the dry-run default, and the need to pass confirm=true for an actual restart. It mentions policy gating and audit logging, but does not explicitly compare to sibling tools like upgrade or plan_node_upgrade, so it lacks explicit when-not-to-use guidance.

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

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

With no annotations, the description fully discloses the upgrade process: building, distributing, checksum-verfying, atomic swap, cycling, and verification. It also mentions policy gating and audit logging. Misses details on node downtime or state during upgrade.

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 purpose, efficient and well-structured. Every sentence adds value without redundancy.

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

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

Given complexity (3 params, 0% schema coverage, no annotations) and presence of output schema, the description covers the process, dry-run vs confirm, and policy constraints. It does not explain the output but that's not required per rules. Differentiating from 'plan_node_upgrade' would improve completeness.

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

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

Schema description coverage is 0%, so the description must compensate. It adds meaning for 'confirm' (executes vs dry-run) and 'target_version' (the version to upgrade to), but does not explain the 'name' parameter (implicitly the node identifier). Partial coverage.

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 upgrades a node to a target version, detailing steps like building, distributing, and swapping. However, it does not explicitly differentiate from the sibling tool 'plan_node_upgrade', which might be a planning alternative.

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 explains the dry-run default and execution with confirm=true, implying when to use it. But it lacks explicit guidance on when not to use it or comparisons to alternatives like 'plan_node_upgrade'.

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?

Explicitly states 'read-only', 'Changes nothing', and describes return format (pass/warn/fail, ok true only when nothing failed). Full disclosure without 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?

Single sentence front-loads purpose but is somewhat dense. Could be split for readability, but still efficient.

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

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

Complete description for a parameterless tool with output schema. Covers scope, checks, and return criteria.

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?

No parameters; schema coverage is 100% by default. Description adds value by explaining what the tool checks without needing 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?

Description clearly states 'read-only readiness check of the whole fleet' with specific areas (SSH, service, binary, disk, RPC, cores, RAM, disk, toolchain, DNS credential presence). Distinguishes from sibling tools like 'fleet_status' or 'node_detail' by focusing on readiness validation.

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?

Implicitly clear that it's for pre-deployment readiness checks. Context of sibling tools (e.g., 'fleet_status', 'plan_node_upgrade') suggests when to use. But missing explicit when-not or alternatives.

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

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

With no annotations, the description carries full burden. It states the core function and a key behavioral nuance (drift != outdated), but lacks disclosure of read-only nature, performance impact, or output characteristics.

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

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

Two sentences with zero wasted words. Front-loaded with action ('Compare each node's...'). 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 no parameters, no annotations, and an output schema (not provided), the description covers the essential purpose and nuance. It is sufficiently complete for a simple reporting 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?

No parameters exist, so schema coverage is trivial (100%). The description doesn't need to add parameter details, and baseline for zero-parameter tools is 4.

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 ('Compare') and resource ('solana-core version') and clearly states the scope ('each node against its cluster's reference RPC version'). It distinguishes itself from sibling tools like node_detail or validate by focusing on version drift.

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

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

No explicit guidance on when to use this tool versus alternatives. It mentions a nuance about drift not always indicating outdatedness, but doesn't specify contexts or 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 provided, but description declares 'Read-only' and lists included data. Missing behavioral details like authentication needs, rate limits, or side effects.

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

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

Front-loaded with main purpose, but the list of details makes it slightly wordy; still 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?

Provides a good overview of returned data for a read-only tool, though error conditions or prerequisites are not mentioned.

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

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

Schema has one parameter 'name' with 0% description coverage; the tool description does not explain what 'name' refers to (presumably validator identity), so it adds no meaning 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 shows 'voting health of a validator that a plain RPC check can't show' and enumerates specific details, but does not explicitly differentiate from the many sibling 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?

Implied usage when plain RPC is insufficient, but no explicit when-not-to-use or alternatives among the 15 sibling tools are provided.

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