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

Annotations already declare readOnlyHint=true, destructiveHint=false, so the lack of mutation is clear. The description goes beyond annotations by detailing the step-by-step behavioral flow, the return format ({name, link}), and the order dependency of parameters. It does not contradict annotations (no destructive or read-write claims), and adds useful transparency about how the tool chains to other tools.

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 description is a single paragraph of about 110 words, which is compact for a hierarchical navigation tool. Sentences build logically from overall purpose to specific examples. It could be slightly tighter (e.g., 'feed the chosen name into the next-level arg' is slightly wordy), but every sentence adds value. No redundancy or 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?

Given the tool's complexity (5 parameters, hierarchical dependency, no output schema), the description is remarkably complete. It explains the entire usage flow, return shape ({name, link}), and connection to the downstream tool get_metric_data. Combined with the well-annotated schema and annotations (readOnlyHint, idempotentHint), the agent has all necessary information to use this tool 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?

The input schema covers all five parameters with 100% description coverage, but the descriptions are minimal (only example values). The tool description compensates by explaining the logical order and dependencies: 'Pass the levels you already know (in order...)' and 'with no args it lists themes.' It also clarifies constraints like 'Requires theme + sub_theme' for topic and 'Requires the levels above' for geography. This transforms the schema from a list of fields into a usable sequence.

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 uses specific verbs ('walk', 'discover', 'list') and clearly identifies the resource: the UKHSA surveillance hierarchy. It explains that the tool returns options for the next level based on currently known levels, and gives explicit examples of the hierarchy (theme, sub_theme, topic, geography_type, geography, metrics). This differentiates it from siblings like get_metric_data or list_metrics, which are for obtaining data rather than browsing the hierarchy.

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 explicitly states when to use the tool: to discover valid values for the next level in the hierarchy. It provides a clear step-by-step progression (no args → themes, theme → sub_themes, etc.) and even tells the user to call get_metric_data after obtaining all six levels. This gives strong usage context, though it does not explicitly mention when not to use it (e.g., if you already know all values), so it misses full exclusion guidance.

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