GOV.UK

Search within a GOV.UK content body

govuk_grep_content

Read-onlyIdempotent

Find body sections in a GOV.UK content item matching a pattern.

Returns a list of {anchor, heading, snippet, match} hits — small per-section snippets centred on the match — so the LLM can decide which full sections to read via govuk_get_section.

Use this when answering content-based questions ("what does this guide say about X?", "find the bit about eligibility") rather than navigating by section number.

Pattern is regex; if it doesn't compile, falls back to literal substring.

Input Schema

TableJSON Schema

Name	Required	Description
`pattern`	Yes	Regex or literal substring to search for within the page body, e.g. 'payment' or 'eligible.*income'
`max_hits`	No	Maximum number of matching sections to return (1–100)
`base_path`	Yes	GOV.UK base_path, e.g. '/guidance/register-for-vat' or '/universal-credit'
`case_insensitive`	No	If true (default), match case-insensitively

Output Schema

TableJSON Schema

Name	Required	Description
`hits`	Yes	Matching sections in document order
`pattern`	Yes	The pattern that was searched for
`base_path`	Yes	The content item that was searched
`truncated`	Yes	True if hit count reached max_hits and more matches may exist

TDQS

A4.9/5.0

Behavior5/5

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

Annotations already declare readOnlyHint/idempotentHint, so the description adds value by detailing the return structure (`{anchor, heading, snippet, match}`) and the fallback behavior: 'Pattern is regex; if it doesn't compile, falls back to literal substring.' This discloses edge-case behavior beyond the annotations.

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

Conciseness5/5

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

Four short paragraphs, each with a distinct purpose: purpose, return format, usage guidance, and pattern behavior. No redundant sentences; front-loaded with the core action.

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?

The description covers what the tool returns, when to use it, how it relates to sibling tools, and the regex fallback. Given the output schema exists, it doesn't need to enumerate return fields, but it does anyway for clarity. The tool's complexity is well handled.

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

Parameters4/5

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

Schema coverage is 100%, so baseline is 3. The description adds the fallback semantics for `pattern` and explains that hits are per-section snippets, giving extra meaning to `max_hits` and `pattern` beyond the schema. This additional nuance raises it to 4.

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 opens with a clear verb+resource+scope: 'Find body sections in a GOV.UK content item matching a pattern.' It distinguishes itself from siblings by referencing govuk_get_section and contrasting with 'navigating by section number,' making its purpose unambiguous.

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

Usage Guidelines5/5

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

Explicit usage guidance is provided: 'Use this when answering content-based questions ... rather than navigating by section number.' It also prescribes a workflow: 'so the LLM can decide which full sections to read via govuk_get_section,' naming an alternative tool and the condition for its use.

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

All GOV.UK tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.6/5.0

Disambiguation5/5

Each tool targets a distinct operation: page metadata, sections, content search, organisation profiles, organisation listing, postcode lookup, and full-text search. No two tools overlap in purpose, so an agent can clearly differentiate them.

Naming Consistency5/5

All tools follow the 'govuk_verb_noun' pattern (e.g., govuk_get_content, govuk_list_organisations) using imperative verbs. The naming is uniform and predictable, with only minor variation in verb choice (get, grep, lookup) but no mixing of conventions.

Tool Count5/5

Seven tools is ideal for the scope of reading GOV.UK data: page content (3 tools), organisations (2), postcode lookup (1), and search (1). Each tool serves a necessary function without being excessive or insufficient.

Completeness5/5

The tool set covers the primary read operations for the domain: retrieving page structure and content, searching across content, browsing and fetching organisations, and looking up postcodes. While there is no single tool to fetch all sections at once, the combination of get_content and get_section covers it adequately. No obvious gaps for a read-only API.

Resources

Need Help?