cometbft-mcp

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantive behavior: votes reflect one node's view with a default of a synced sentry or full node, validators are labeled by config name or staking moniker, and monikers are wrapped in <untrusted> tags with an explicit instruction to treat them as data. It also pre-classifies outcomes (no_quorum, stuck_with_quorum, many_rounds) so the agent knows how to interpret results.

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 what is inspected, then when to use it, then how to read findings. Dense but essentially every clause carries information; the single long paragraph could be broken into shorter sentences or bullets for faster scanning, which keeps it from a 5.

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 one-parameter read-only diagnostic with an output schema, the description covers the interpretive layer the schema cannot: what the vote data means, the three finding categories, and the trust boundary on monikers. An agent has everything needed to call it and to act on the result.

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% and the single param is documented, so the baseline is 3; the description earns above that by explaining the semantics of choosing a node — that results are one node's view and the default is a synced sentry or full node. There is a mild tension with the schema's 'omit to check every configured node', which could confuse whether omission means one default node or all nodes.

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

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

States a specific verb and resource ('Inspect the live consensus round') and enumerates exactly what is returned: height, round/step, time at height, per-validator prevotes/precommits, and >2/3 voting-power status. This is clearly distinct from siblings like fleet_overview or validator_health, which operate at fleet/validator scope rather than live consensus state.

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 trigger conditions — 'when the chain or a node stops producing blocks (stale_head, upgrade_halt)' — and the questions it answers ('who is missing?', 'quorum problem or something else?'). It does not name sibling tools or state when NOT to use it (e.g., for healthy-chain monitoring), so it falls just short of a 5.

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

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

Annotations already declare read-only, idempotent, non-destructive and open-world, so safety is covered. The description adds real context beyond them: full-fleet scope, the 50-block signing window, and the notable performance trait of being slower than single-purpose tools on large fleets. The return-shape sentence is partly redundant with the output schema, which keeps it from a 5.

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

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

Front-loaded with the sweep's purpose, then usage, then return shape, then the cost caveat - a sensible progression with no filler. The return-format sentence retreads ground already covered by the output schema, which is the only waste.

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

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

With zero parameters, full annotation coverage and an output schema, the description needs only to position the tool and set expectations. It does both: it routes agents here first for broad checks and warns about latency on large fleets.

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 tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline is 4. The description correctly implies the sweep is unscoped and applies to all configured nodes rather than allowing filtering.

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

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

States a specific action (one-call health sweep) over a specific resource (every configured node and validator) and enumerates the dimensions checked: sync, peers, signing liveness over 50 blocks, jail risk, and scheduled upgrade. It is clearly distinguishable from the single-purpose siblings it names.

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

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

Explicitly says to use it first for broad questions like "is everything ok?" or a daily check, then names node_status, peer_health and validator_health as the drill-down alternatives. It also flags the tradeoff (slower than single-purpose tools on large fleets), which implicitly tells the agent when not to use it.

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 the readOnly/idempotent annotations, it enumerates what each node record contains (level, findings with codes, height, catching_up, blocks behind fleet max, versions, consensus address/voting power). It also flags a security-relevant trait the annotations never express: monikers and versions are wrapped in <untrusted> tags and must be treated as data, not instructions.

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 the recommended-first-use case are front-loaded, then the return payload, then exclusions, then the untrusted-data caveat. The per-node field list is long but it is genuinely informative rather than 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?

An output schema exists, yet the description still summarizes the shape of the return value, names the sibling alternatives, and covers the untrusted-content handling. Nothing an agent needs in order to select and call this tool 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% and the single `node` parameter already documents that omitting it checks every configured node. The description only reinforces the fleet-wide framing implicitly, so it adds little beyond the schema; 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?

States a specific verb and resource ("check whether CometBFT nodes are synced and following the chain head") and immediately separates itself from siblings by naming what it does not cover. An agent can distinguish it from peer_health and validator_health without opening any 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 prioritization ("Use it first when asked if a node or the fleet is healthy, or when a validator may be falling behind") and explicit exclusions routing to peer_health and validator_health. Both the when and the when-not are covered.

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 this a read-only, idempotent, non-destructive operation, and the description adds substantial context beyond them: result shape (per-node findings plus a peer list capped at 40, longest-lived first), a redaction policy governed by --reveal-network, and an explicit warning that monikers arrive wrapped in <untrusted> tags and must be treated as data. Those are exactly the behaviors an agent could not infer from 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?

Purpose and triggering conditions are front-loaded, followed by output shape and then the safety caveats. Every sentence carries operational value — the redaction and untrusted-content notes directly prevent agent errors rather than padding the 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?

An output schema exists, so the description need not detail return values, and it correctly stops at the high-level shape. For a read-only diagnostic with one optional parameter, nothing an agent needs — when to call it, what it returns, how to interpret redacted output, how to handle untrusted strings — 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?

The single `node` parameter is already fully documented in the schema, but the description reinforces the omit-to-check-all behavior with "at most 40" and per-node framing, clarifying what happens at the default. Little is added beyond the schema, which caps this at 4 rather than 5.

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 ("Check p2p connectivity of CometBFT nodes") and enumerates the exact signals produced: peer count, inbound/outbound split, public-address peers, cross-chain peers. That scope is clearly distinct from sibling tools such as validator_health, consensus_diagnosis, and node_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?

Gives concrete triggering conditions ("when a node is isolated, catching up slowly, or to verify a sentry topology") plus the expected invariant for a sentry setup, which tells the agent what a good result looks like. It does not name a sibling alternative or an explicit when-not-to-use case, so it stops short of the top band.

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 annotations already declare the operation is read-only, idempotent and non-destructive, and the description adds real substance beyond them: the returned x/upgrade plan fields, voting-period proposals, per-node app and CometBFT versions, the named findings (upgrade_soon, upgrade_halt, version_skew), and the blind spot on binary staging. The prompt-injection warning about <untrusted> tags is a genuinely important behavior the agent could not infer from 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?

It is front-loaded with purpose, then triggers, then return contents, then limits, and last the untrusted-data caveat. Every sentence adds information, and nothing is padding even though the description is long.

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?

Because the tool has no parameters, a rich return surface (including an output schema) and annotations covering safety, the description needs only to convey scope, triggers, outputs and limits. It covers all of these, including the untrusted-data handling, without leaving gaps.

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

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

This tool takes no parameters, so there is nothing for the description to disambiguate; the baseline applies. The description correctly avoids inventing input concepts.

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

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

The description gives a concrete verb and resource: it checks the chain's scheduled software upgrade and fleet readiness for it. It names exactly what is not covered (whether the new binary is staged on each host), so an agent can distinguish it from siblings such as fleet_overview or consensus_diagnosis.

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 three explicit triggers: questions about upcoming upgrades or hard forks, a chain that looks halted, and pre-maintenance checks. It also states a clear out-of-scope caveat, telling the agent to say so instead of assuming, which functions as guidance on when not to claim coverage.

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 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.