Builder Leaderboard

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

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses a material data caveat: 'Attributed metrics slightly undercount versus ledger revenue because trigger-order fills (stop/TP) are not yet attributed.' It also explains the 'verified' stamp and that builderName is omitted when unknown, which are useful behavioral details. The access-tier requirement is an additional disclosure annotations don't capture.

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 dense but purposeful: it front-loads the core purpose, then enumerates returned fields, adds the undercount caveat, and closes with use cases. The em-dash-heavy structure makes it slightly harder to parse, but every clause adds information an agent needs. It earns a high score for no wasted sentences, though it could be tightened.

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 no output schema present, the description carries the burden of describing return values, and it does so thoroughly: fill volume, distinct users, fill counts, preceding-window deltas, feeTenthsBp, and builderName. It also tells the agent where to look for caveats (dataNotes) and what 'verified' means. Combined with the schema and annotations, nothing essential is missing for calling this tool 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?

All four parameters (limit, offset, period, useToonFormat) already have full descriptions in the schema, so baseline is 3. The tool description reinforces the period semantics ('immediately preceding window for deltas') and references feeTenthsBp as an output field, but it adds no new parameter-level guidance beyond the schema. Since schema coverage is 100%, the description need not compensate.

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 precise definition: 'Builders (HIP-3 dexes, frontends, bots) ranked by exact revenue from Hyperliquid's on-chain cumulative builder-fee ledger over the requested period.' This specifies the verb, resource, and data source, and distinguishes it from sibling builder_* tools that focus on profiles, fills, or traders. The inclusion of 'Use for...' question templates further anchors what the tool answers.

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 two canonical use cases: 'which builders earn the most?' and 'is builder X growing?', giving an agent a clear decision rule for selecting this tool. It also states the access precondition ('Requires Starter tier or higher'), but does not name alternative builder_* tools or give a when-not-to-use condition, so it stops short of full differentiation.

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