cricketaustralia_standings

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

Annotations already declare readOnly, openWorld, and idempotent hints. The description adds value by specifying the exact return structure (standings list with fields) and the behavior for competitions without a points table (empty). It also states that no auth is needed, which is consistent with the annotations and adds practical context.

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 remarkably concise: two short paragraphs that define the tool's purpose, note the required parameter, list the return fields, and state auth requirements. Every sentence contributes information without redundancy, and the structure is front-loaded and easy to scan.

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's simplicity and the presence of rich annotations and a full schema, the description covers all essentials: what it returns (including the responseError field), the required parameter, and a caveat about empty results. It does not explain ordering or pagination, but those are not critical for a simple read-only ladder tool.

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%, so the baseline is 3. The description goes beyond by reiterating the necessity of competitionId and explains the empty-result case for competitions lacking a points table, which adds behavioral meaning to the parameter. The source of the ID is also mentioned, though it is already present in 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 identifies the tool as retrieving a competition ladder with per-team statistics like played/won/lost, points, and net run rate. It specifies the resource (Cricket Australia standings) and distinguishes itself from sibling standings tools by naming the sport and the key requirement of a competitionId.

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 gives clear context: use it for Cricket Australia competition standings, and notes that competitionId is required (with the caveat that competitions without a points table may return empty). It does not explicitly mention alternative tools for other sports, but the context is unmistakable given the tool name and the pointer to the competitions tool for obtaining the ID.

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