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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds genuinely non-obvious behavior: the alternatives computation (venues matching everything but that week, each with nearest earlier/later free Saturday), the whole-catalogue default when no filters are given, and the mutually exclusive date/months modes. It stops short of describing the output shape or the Saturday-only constraint, which lives in the 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?

The core purpose is front-loaded and every clause carries information — there is no filler or restating of the schema. The description is dense and long, but the length is justified by 21 optional parameters; it would earn a 5 with slight structural segmentation of the modes and filter groups.

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?

For a 21-parameter, zero-required-parameter search tool with no output schema, the description covers the default behavior, both query modes, filter combinations, and the category dependency quite thoroughly. Minor gaps: it never sketches the returned venue fields, and the Saturday-only date rule is left entirely to the schema.

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 coverage is 100%, so the per-parameter baseline is already satisfied. The description adds value by organizing the 18+ filters into semantic groups (party size, lake facts, facilities) and by explaining the interplay of 'date' vs 'months' and the 'category'→search_categories dependency beyond what each parameter's own description 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?

Opens with 'The tool for "find me a lake"' and a specific verb+resource: 'search the Angling Lines catalogue by party size, features and availability.' This clearly positions it as the full catalogue search and distinguishes it from search_categories (the slug source) and the more targeted sibling tools.

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?

Provides explicit usage context: call with nothing for the whole catalogue, combine filters, add a 'date' for availability plus alternatives, or use 'months' to scan whole months, and narrow with 'category' using slugs from search_categories. It names one cross-tool dependency but never states when NOT to use this tool versus siblings like venues_available_on_date or list_venues.

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