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

Annotations only cover read-only/non-destructive/open-world, but the description adds genuinely new operational context: BKFC round stats require the Starter plan and degrade to a partial note on Free, the call is parallel-safe, and upstream cost is 1-2. The tier-gating disclosure in particular is something an agent could not learn from annotations or schema.

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?

Labeled sections (RAF, BKFC, prerequisite, parallel-safety, example) make it scannable and the core purpose is front-loaded in the first line. It is denser than strictly necessary for a 3-parameter tool, but every block carries distinct information rather than 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?

With an output schema present, return values need not be re-explained, yet the description still summarizes the payload, the plan-dependent limitation, the ID prerequisite, concurrency safety, and an example invocation. Nothing an agent needs to call this correctly is missing.

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 100%, so the baseline is 3, and the schema already documents league, boutId, and includeBreakdown. The description adds meaning beyond the schema by spelling out what the breakdown parameter actually yields per league (per-PERIOD scores for RAF vs per-ROUND punch stats for BKFC) and by confirming the boutId format with a league-qualified example.

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 first sentence names a specific verb and resource ('One RAF or BKFC bout in full, with its scoring breakdown') and the body enumerates exactly what is returned per league. An agent can immediately distinguish this from combat_card (cards/events) and combat_athlete (athlete-level data) among the siblings.

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?

It explicitly tells the agent where the required boutId comes from ('Get boutId from combat_card or combat_athlete') and supplies a concrete example call, which is strong prerequisite guidance. It stops short of stating when NOT to use it (e.g. versus combat_h2h for matchup context), so it is clear context without explicit exclusions.

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