purchase_stats

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It covers several key behaviors: makes no purchase, makes one logical GET request, does not auto-fetch continuation pages, limits array responses to 100 rows and 256 KiB with truncation reported, and refuses oversized records without partial fields. It also notes data structure variability. This is substantial transparency, though it does not detail error handling or response format.

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 all sentences contribute relevant information. It front-loads the purpose and then lists behavioral constraints. It is not overly verbose, though it could be slightly tightened by removing the ambiguous filter mention. Overall, it is well-structured and efficient.

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 read-only stats tool with no parameters and no output schema, the description covers many important aspects: public scope, no purchase, request behavior, pagination, response limits, truncation, refusal, and data structure variability. It is fairly complete. The only gap is the misleading filter reference, which detracts from completeness, and it does not describe the response shape beyond mentioning arrays.

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?

The input schema has zero parameters, so the baseline is 4. However, the description mentions 'Required inputs' and 'Other declared filters are forwarded as supplied,' implying that parameters exist, which directly contradicts the empty schema with additionalProperties:false. This introduces confusion and undermines parameter clarity. The description does not add meaningful parameter semantics and instead conflicts with the schema.

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 reads public pack and promotional-card statistics, with a specific verb and resource. It also clarifies it makes no purchase, which helps distinguish it from purchase-related tools. However, it does not explicitly name sibling tools or contrast its scope, so it falls short of full differentiation.

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 explicit guidance on when to use this tool versus alternatives. It mentions 'Required inputs reflect tool policy' and 'Other declared filters are forwarded as supplied,' but these are about inputs, not usage context. There is no mention of alternative tools or conditions that would select this one over others, leaving the agent to infer usage.

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