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

Annotations already establish readOnly, openWorld, idempotent, and non-destructive behavior, so the description adds value by describing the return shape, including section id, URL, published_at, and age_days. It also clarifies the nature of the content as HMRC's working interpretation. No contradiction with annotations exists.

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 front-loaded with the core purpose and remains tightly organized: scope, examples, return fields, narrowing guidance, and next-step routing. The long list of tax topics is somewhat dense but gives useful coverage signals without being redundant.

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 search tool with no output schema, the description adequately specifies what it matches, what fields it returns, how to narrow results, and where to retrieve full text. Combined with a fully documented input schema, everything needed to select and invoke the tool correctly is present.

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 explains all five parameters clearly. The description adds little param-specific detail beyond mentioning the manual argument, and the EIM/CG section-id examples illustrate return values rather than parameter semantics. Baseline 3 is appropriate.

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 and resource: 'Find the section of an HMRC internal manual that answers a UK tax question asked in plain words'. It clearly differentiates from sibling tools by noting that full text is retrieved via hmrc_manual_section, while this tool performs the search. The included topic examples make the intended scope concrete.

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 provides clear guidance on when to use the tool: for plain-word UK tax questions where HMRC's own manual-level interpretation is needed. It also explains how to narrow results with the manual argument and directs users to hmrc_manual_section for full text. It does not explicitly discuss when to prefer hmrc_manuals or hmrc_manual_changes, but the usage context is strong.

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