Skip to main content
Glama

Hmrc Manual Search

hmrc_manual_search
Read-onlyIdempotent

Find the section of an HMRC internal manual that answers a UK tax question asked in plain words, salary sacrifice, benefits in kind, travel and subsistence expenses, termination payments, share schemes, residence and domicile, capital gains reliefs, VAT liability, IR35 and off-payroll working, pension annual allowance, inheritance tax reliefs, penalties and compliance. This is HMRC's own working interpretation of the UK tax code, section by section, and it is the level at which UK tax questions are actually answered. Returns each matching section with its manual, its section id (EIM42750, CG12345 and the like), its URL, its published_at date and age_days. Narrow to one manual with the manual argument. Retrieve the full text of a hit with hmrc_manual_section.

Example tool call

This call uses example arguments supplied in the tool’s input schema.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "count": 5,
      "query": "salary sacrifice pension contributions"
    },
    "name": "hmrc_manual_search"
  }
}

Input Schema

NameRequiredDescriptionDefault
countNoSections to return, 1-100 (default 20).
queryYesThe tax question or topic in plain words, e.g. "salary sacrifice pension contributions" or "when is travel to a temporary workplace deductible".
startNoOffset for paging.
manualNoRestrict to one manual, as a base_path or slug, e.g. "/hmrc-internal-manuals/employment-income-manual" or "employment-income-manual". Get these from hmrc_manuals.
include_other_departmentsNoAlso search non-HMRC departmental manual sections. Default false.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.2/5.0
Behavior4/5

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

Because the annotations already establish readOnlyHint, idempotentHint, and openWorldHint=true, the safety profile is covered by structured data. The description adds useful behavioral detail by stating exactly what comes back for each hit: manual, section id such as EIM42750, URL, published_at, and age_days. It does not explain paging beyond the start parameter, but it does state that the tool returns this HMRC-internal interpretation rather than statutory text.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the purpose, and each sentence has a job: what it searches, what it covers, what it returns, how to narrow, and what to do next. The long enumeration of tax topics makes the first sentence dense, but those topics are retrieval-relevant, so the extra length is justified.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description correctly fills that gap by describing the returned fields and their formats. All five parameters are either documented in the schema or described in the prose, and the follow-up tool is named. Nothing material is missing for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and every parameter, including count, start, manual, and include_other_departments, is already documented in the schema. The description notes that manual narrows the search and points to hmrc_manuals as the source for manual slugs, but it essentially repeats what the schema already says. The baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource: 'Find the section of an HMRC internal manual that answers a UK tax question.' It also enumerates the tax domains covered, such as salary sacrifice, IR35 and capital gains reliefs, and calls out the explicit contrast with hmrc_manual_section, which returns full text. As a result, an agent can distinguish this tool from its sibling without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a clear trigger, a plain-words tax question, and a clear follow-up path: use hmrc_manual_section to retrieve the full text of a hit, and narrow to one manual when the user already knows the manual. It does not say when to prefer gov_uk_content_search over this tool or when to exclude non-tax questions, so it is strong but not fully exclusive.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.