Validator signing liveness

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

Beyond the readOnly/idempotent annotations, the description discloses the data source (commit signatures via a synced sentry/full node), the failure-tolerance property (works while the validator node is down), and how to interpret results (miss_streak ≥ 3 means not signing right now). It also warns against recomputing jail metrics and instead quoting them from the result, which is genuinely actionable behavioral guidance.

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?

Purpose and usage are front-loaded, then a return-value inventory, then the quoting instruction. The long enumeration of returned fields partly duplicates the output schema, but the interpretation cues (miss_streak threshold, cosmos slashing fields) justify most of the 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 two-parameter diagnostic read tool with an output schema, the description covers what it does, when to use it, where data comes from, how to read the key indicators, and a caution about quoting rather than computing jail figures. Nothing an agent needs to invoke or interpret it correctly 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 coverage is 100%, so both parameters are already documented, including the window range/default and the node-omission rule. The description mostly restates the window default and adds no new syntax or behavioral nuance per parameter, 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 opens with a specific verb and resource: checking whether a validator is signing blocks, sourced from commit signatures over the last N blocks. It is clearly distinguishable from siblings like node_status or consensus_diagnosis because it is scoped to a single validator's signing liveness and set membership.

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 trigger conditions: asked if a validator is up, missing blocks, at risk of jailing, or out of the active set. It also states the key operational prerequisite (a configured synced sentry/full node is used, so it works while the validator is down). It does not name sibling alternatives or when-not to use it, which keeps it at a 4.

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