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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior, so the description is not carrying the safety burden. It does add real value beyond them by disclosing per-route return fields (ratio as from:to, transfer time, minimum, annual limit, card restriction, grade, check date, source, transfer page), giving the agent a clear picture of result shape despite there being no output 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?

Two sentences, both earning their place: the first orients the agent, the second specifies the exact shape of each returned route. The field list is long but information-dense rather than padded; the closing reference to getbrief.cards is mildly promotional but also tells the agent where the transfer page link points.

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 zero required parameters and no output schema, the description should clarify the no-argument behavior (all routes?) and whether include_closed defaults to excluding closures. The rich per-route field enumeration partly compensates, but the tool's most consequential ambiguity — what an unfiltered call returns — is left unaddressed.

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 schema already documents all three parameters including include_closed. The description adds only directional nuance ("out of it and into it" for programmes versus "routes its points take" for cards) and does not explain what happens when no parameter is supplied, nor clarify interaction between card and programme.

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?

"Where points can move, by programme or by card" names the resource (transfer routes and ratios) and enumerates two concrete lookup modes with example values ("Marriott Bonvoy", "Axis EDGE Miles"). An agent can tell this is a transfer-partner/ratio lookup, but nothing in the text distinguishes it from siblings like get_card or search_cards, which may also surface card-level data.

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 usage by contrasting what a programme returns ("routes out of it and into it") versus what a card slug returns ("the routes its points take"), which is genuinely helpful routing guidance. However, it never states when to prefer this over search_cards or get_card, whether the two parameters are mutually exclusive, or which takes precedence if both are supplied.

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