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

The description adds useful behavior beyond the annotations by noting 'opaque cursor pagination' and specifying that volume is in shares while PnL is in USD. The annotations already cover read-only, idempotent, non-destructive behavior, so the added pagination and unit context are valuable. It does not detail response shape, but an output schema exists.

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 two short sentences with no filler. The alias relationship is front-loaded, followed by the core action and key units, making it scannable and efficient for an agent.

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?

Despite having an output schema and safety annotations, this is a moderately complex query tool with 8 optional parameters covering ordering, time periods, categories, and filters. The description leaves those dimensions unexplained secret and does not clarify pagination behavior beyond saying it is opaque. This is incomplete for reliable invocation in varied use cases.

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?

With schema description coverage at only 13%, the description needed to compensate, but it only clarifies the meaning of volume/PnL and hints at cursor pagination. The tool has 8 parameters including orderBy, category, timePeriod, userName, and walletAddress, none of which are explained in the description. This leaves the agent under-informed about filtering and ordering semantics.

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 states a specific action and resource: 'Get ranked public Polymarket traders' with clear metric definitions ('volume in shares and PnL in USD'). It also calls out that it is an alias of polymarket_get_trader_leaderboard, distinguishing it from wallet- and market-specific getter tools in the sibling list.

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 this tool is relevant: retrieving the public trader leaderboard. The alias declaration explicitly names the equivalent sibling, and the resource-focused wording makes the intended use obvious. However, it does not give exclusions or contrast with related tools like get_public_profile or get_wallet_pnl.

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