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

Annotations already mark this as read-only/idempotent/non-destructive, and the description adds valuable context beyond them: the source ('cwsi.net's calculator and the airline's published rules') and its unofficial status, the rounding-down-with-no-minimum rule, the 0.5-segment exception for Amman–Aqaba/Tel Aviv, and the fact that Tier Miles are not returned. It does not discuss confidence/precision caveats for the fare-family-to-booking-class mapping, which it admits is 'our reading.'

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 earning formula is front-loaded and each subsequent sentence carries a distinct rule (segments, noearn, tier progress, segs format). It is dense with minor redundancy — the segs entry rules and the Amman–Aqaba/Tel Aviv exception are stated in several places — but almost every sentence earns its place for a rule-heavy calculator.

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, the description need not explain return values, and it fully covers the input complexity: the fare-family/tier rate model, segment counting, the eligibility flag, tier-progress semantics, and the partner-crediting path. Nothing an agent needs to invoke this 10-parameter, rule-heavy tool 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; the description earns an extra point by adding meaning the schema lacks, such as the percentage ranges per fare family and tier (50%–200% Bronze to 125%–275% Platinum Hawk), the half-segment rule, and that noearn Y means 'earns nothing.' It does not, however, explain how the creditTo/creditStatus/creditClass trio interacts beyond what the schema already states.

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+resource: 'Royal Jordanian Royal Club Award Miles and segments for Royal Jordanian flights,' which immediately distinguishes it from the ~50 sibling calculate_*_miles tools. It also names what it explicitly does not compute ('Tier Miles are not calculated') and defers segment-distance computation to calculate_flight_distance, further sharpening its scope.

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 gives clear operating conditions: use fare family + tier to derive the earn rate, set noearn=Y for award or ≥50% discount tickets, and use qs only for tier progress. It also routes to creditTo for partner programs versus leaving it out for Royal Jordanian's own program. It stops short of naming alternatives (e.g., compare_fare_classes) when a user is deciding which fare family to credit.

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