Search UK Open Data

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

With no annotations, the description carries the full behavioral disclosure burden. It notes 'No API key required' and that results include titles, publishers, formats, and links, which is useful. But it omits rate limits, pagination behavior, whether the search supports filtering, and failure modes. This is a thin behavioral profile for a network-backed search tool.

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?

Three short sentences: purpose, return fields, and an operational note. Every sentence delivers information and is front-loaded with the primary action. No filler or redundancy.

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 simple two-parameter search tool with a fully documented schema and no output schema, the description covers the essentials: what it searches, what it returns, and that no auth is needed. However, without annotations it should do more to explain return shape (e.g., result count limits, pagination), and it doesn't help distinguish from the many sibling query tools. It is minimally complete but leaves gaps.

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 baseline is 3. The description adds a concrete example of the catalogue domain ('data.gov.uk') and mentions the returned fields, which slightly enriches understanding of what the query parameter targets, but it doesn't add parameter syntax or format detail beyond the schema. The example-driven schema already provides good guidance, so the description is adequate but adds marginal value.

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 states a clear verb+resource: 'Search the UK government's open data catalogue (data.gov.uk).' This distinguishes it from the many query_* siblings that appear to target specific data domains (crime, housing, weather, etc.), since this is a general catalogue search. However, it does not explicitly name or contrast with those siblings to help an agent choose.

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 implies usage by naming the catalogue to search, but offers no explicit when-to-use guidance or alternatives. Siblings like list_available_data or the numerous query_* tools could overlap, yet the description doesn't state when this broad search is preferable. No exclusions or prerequisites are given.

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