list_solana_validators

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

Annotations already indicate read-only, idempotent, and open-world behavior. The description adds crucial context: it's a helper (not the source of truth), data comes from an external public feed, default filters and sort are provided, and the response includes a `notes[]` field with instructions. This aligns with and enriches the annotations without 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 description is informative and front-loaded with the purpose, but it is somewhat lengthy due to the inclusion of the INVARIANT #14 note. While every part adds value, it could be slightly more concise. However, it maintains clear structure and 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 there is no output schema, the description compensates by explaining the output columns (wizScore, commission, MEV, APY, stake, etc.) and the presence of a `notes[]` field. All input parameters are covered, and the usage context is fully described. The tool is complex (nested filters, multiple sort options), and this description is complete for an agent to use 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% (all parameters have descriptions). The description further explains defaults (excludeDelinquent=true, excludeSuperminority=false, limit=25, sortBy='score'), the rationale for each filter (e.g., excludeSuperminority is a network-health choice), and the meaning of sort by options. This adds significant decision-making context 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's a read-only validator-ranking helper for `prepare_native_stake_delegate`. It specifies the data source (stakewiz.com public feed), the output columns relevant to delegation, and explicitly instructs to use this before the delegation tool. This distinguishes it from sibling tools by defining its role as a preparatory step.

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

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

The description provides explicit when-to-use guidance ('USE THIS BEFORE prepare_native_stake_delegate') and what the agent should do with the output (surface a ranked menu). It also includes an 'INVARIANT #14 NOTE' with detailed post-use steps for the user (open stakewizUrl, byte-equality-check votePubkey), leaving no ambiguity about the workflow.

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