player_leaderboard

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

With no annotations, the description carries the full burden and does so thoroughly. It discloses pagination behavior, single-request behavior, local row and byte limits, truncation reporting, refusal of oversized records, and the fact that filters are forwarded without implied effectiveness.

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 front-loads the purpose and packs in useful behavioral details, but the empirical probe narrative (default 20 rows, modern-format 26, limit=2/offset=2 returning unchanged rows) is verbose and could be condensed into 'no pagination controls are exposed.' It is informative but not tightly edited.

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 simple three-string-parameter tool with no output schema and no annotations, the description covers many behavioral edge cases and response limits. Still, it omits the shape of a leaderboard row, any error behavior, and clear required-parameter semantics, so an agent would still have to probe or infer some essential calling details.

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 description coverage is 0%, so the description needed to compensate. It identifies the three selection dimensions and notes that required inputs reflect tool policy, and that declared filters are forwarded as supplied. However, it does not explain expected value formats, which parameters are actually required, or the meaning of each filter beyond its name.

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 names a specific operation ('Read the ranked leaderboard rows') and the selection dimensions (season, leaderboard, format). It is clear about what the tool returns at a high level, though it does not contrast itself with sibling tools such as player_leaderboard_with_player or player_richlist.

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 no guidance on when to choose this tool over alternatives and names no sibling tools. It gives behavioral caveats (no pagination, no auto-fetch) but does not state a use case or exclusions, so an agent is left to infer applicability.

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