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

With annotations already covering read-only/idempotent/non-destructive, the description adds the traits that matter: one row per licence, domain, or premises keyed by stable identifiers (so counts aren't double-counted across grains), source is the Commission's daily register files, and personal licences held by individuals are explicitly excluded from ingestion. It also discloses the credit cost and the unauthenticated preview cap, which no annotation conveys.

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?

Front-loaded with what the dataset contains before moving to grain, provenance, filtering, and cost — a sensible order for an agent skimming. It is one dense paragraph, which makes the operational details (cost, preview cap) easy to miss, but virtually every clause carries information.

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?

No output schema exists, and the description compensates by listing returned fields (status, activities, start/end dates, trading names, domains, premises address and licensing authority) and the row grain. Completeness is undercut only by the near-total absence of filter semantics for 21 parameters, which is the main thing an agent needs before calling.

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 0% across 21 parameters, so the description carries the full burden and mostly doesn't: only q ('searches all text fields') and the AND-combination rule are explained. Ambiguous parameters such as is_active (a string, not boolean), activities, licence_type, record_type, outward_code, and the four date bounds are left for the agent to guess, and record_type's meaning is only hinted at via the row-grain sentence.

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?

States a specific verb and resource (query the Gambling Commission operating licence register for Great Britain) and enumerates the licence categories it covers (remote and non-remote betting, casino, bingo, gaming machine, lottery, software). It also names the three row grains (licence, domain, premises), which no sibling tool covers, so an agent can distinguish it from query_uk_companies or query_uk_charities at a glance.

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?

Explains how filtering works (filters combine with AND, q searches all text fields) and states the cost/access model: 1 credit per call with an API key, otherwise a 5-row preview capped at 20 calls/day. It does not give an explicit 'use this when…' trigger scenario, but with 20+ unrelated sibling datasets there is little real ambiguity to resolve.

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