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

Annotations already declare readOnly, non-destructive, idempotent and closed-world, but the description adds genuinely new behavioral context: keyword matching rather than full reading, no sign-in required, nothing saved to an account, and an anonymized check record retained for a year for verification. That is exactly the kind of limitation, privacy and retention detail annotations cannot carry.

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?

Five sentences, but front-loaded with what it takes and returns before the output shape, extraction, matching caveat and privacy notes. Each sentence carries distinct information, though the privacy/retention sentence adds density that could be trimmed.

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 no output schema, the description fully describes the return: applicable schemes, each with its deciding fact, the relevant Untap check and the free guide. Combined with the matching caveat and privacy/retention statements, an agent has everything needed to call it correctly.

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?

With one parameter at 100% schema coverage the baseline is 3, and the schema already supplies a definition plus examples. The description goes further by enumerating the kinds of text accepted and noting that flight numbers, dates, times and amounts are extracted from it, which adds meaning about how to phrase the input.

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?

States a precise verb+resource: takes a plain-language situation and returns the UK refund/compensation schemes that may apply, with the deciding fact, Untap check and guide. The scope enumeration (train, flight, TfL, parking, council tax, water, broadband) makes clear it spans the domains of the individual check_* siblings, though it never names a sibling to differentiate itself explicitly.

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?

Usage is implied — describe a situation to discover applicable schemes — and it cautions that matching is keyword-based so the list is 'a starting point rather than a verdict.' However it never states when to use this discovery tool versus the specific check_train_delay / check_flight_compensation / check_tfl_journeys siblings, nor any exclusions.

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