player_balances

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

With no annotations, the description fully carries behavioral disclosure. It explicitly states: no totalling/conversion, one logical GET request, no auto-fetch of continuation pages, array responses limited to 100 rows and 256 KiB, truncation reported in text and metadata, and oversized records refused. This is exceptionally rich for a read tool.

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 front-loaded with purpose, then details parameters, then behavioral constraints. Each sentence adds information without redundancy. At roughly 150 words, it is moderately sized but efficient. Slight tightening could merge some clauses, but structure is logical and no filler.

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 zero annotation coverage, no output schema, and three parameters, the description covers the essential usage (purpose), parameter semantics, and critical behavioral constraints (pagination, limits, truncation). It does not specify the exact return format (e.g., how balances are represented), but it does mention truncation reporting, which hints at response structure. Minor gap, otherwise complete.

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 0%, so the description must compensate. It explains that 'players selector can contain a comma-separated list' and 'token_type is an upstream filter.' It also covers username and other filters with the note that they are 'forwarded as supplied; their effectiveness is not implied.' This gives meaningful semantics to two parameters and a general caveat for the third, which is adequate.

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 specific verb and resource: 'Read current token balances for the explicitly supplied players.' It clearly distinguishes from siblings by emphasizing 'explicitly supplied' and noting no totalling/conversion, which sets it apart from aggregated balance tools. This is unambiguous.

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 implies usage for retrieving current balances when player identifiers are known, but it does not explicitly name alternative tools (e.g., player_unclaimed_balances, player_archived_balances) or state when not to use this tool. The context is clear but lacks exclusionary guidance.

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