pulse_entity_leaderboard

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 deduplication behavior, exclusion of system/protocol accounts, and requires Pro tier. However, it does not describe whether this is a read-only operation, any rate limits, or the response structure beyond a brief list of fields. For a ranking tool with no annotations, this is acceptable but could be more transparent about performance or auth details.

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 concise (4 sentences) and well-structured, with the core purpose and key differentiator front-loaded. It could be slightly more efficient by combining the first two sentences, but it is not overly verbose.

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 optional parameters, full schema coverage, no output schema, and no nested objects, the description provides enough context for an agent to understand the tool's purpose and differentiate it from siblings. It lacks explicit return value details or examples, but the field list ('entity master address, wallet count, open position count, gross entry notional') partially compensates. The absence of an output schema means the description could be more explicit about the expected JSON structure, but it still rates above average.

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 description adds value by contextualizing the parameters implicitly (e.g., providing defaults and ranges that help understand the tool's output window). It does not explicitly detail each parameter beyond the schema, but since the schema already covers them fully, this is a strong baseline. The description's focus on the tool's purpose rather than parameter details is appropriate given the high 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's purpose: 'Top entities (owners, NOT wallets) ranked by combined gross open entry notional across all their sub-accounts.' It distinguishes itself from a wallet-level leaderboard by explicitly noting it provides a deduplicated view aggregated at the entity level, which differentiates it from similar sibling tools like 'pulse_leaderboard'.

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 clear context for when to use this tool (for entity-level, not wallet-level, analysis) and states that system/protocol accounts are excluded. It lacks explicit 'when-not-to-use' guidance or mention of alternatives like 'pulse_leaderboard' for wallet-level data, but the context is sufficient for an agent to decide.

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