afl_live_audio

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

With no annotations, the description must disclose behavioral traits. It reveals that the output is empty when no game is live, which is helpful. However, it does not mention authentication, rate limits, pagination behavior, or any constraints on the parameters (round, pageSize, compseason). The return format is given but lacks details on fields like 'id', 'name', 'channels'.

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 extremely concise: two sentences, no extraneous text. It front-loads the purpose and key behavioral note (empty when no live game). However, it sacrifices valuable parameter details that could be integrated concisely.

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 (optional filters, no output schema), the description should explain the parameters and how they affect results. The return type hint is given but incomplete. The description lacks enough context for an agent to correctly invoke the tool with filters, making it insufficiently 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?

The input schema has three parameters (round, pageSize, compseason) with 0% description coverage. The description provides no semantic information about these parameters—what they filter, their formats, or expected values. Since coverage is low (<50%), the description was required to compensate but fails completely.

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 'Live AFL audio streams', indicating the tool retrieves current live audio for AFL games. The note about emptiness when no game is live adds context. However, it does not explicitly differentiate from sibling tools like 'afl_live_video' or broadcast channel tools, though the audio focus is clear.

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 the tool should be used when there are live AFL games (returns empty otherwise). No explicit guidance on when to use this versus siblings (e.g., use for audio, not video) or prerequisites (e.g., game must be in progress). No exclusions or alternatives mentioned.

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