site

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

No annotations are supplied, so the description carries the burden, and it does disclose the exact payload (columns, numeric typing, row count, provenance banner). It never states that the call is side-effect free or read-only, and gives no hints on cost, caching, or error behaviour for a zero-argument introspection call.

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?

Two sentences, both earning their place: the first front-loads the return contents, the second states the sequencing. It is tight, though the return enumeration is a slightly dense comma list where a leading "This returns..." would improve scannability.

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?

With zero parameters and no output schema, the description compensates by enumerating the returned fields, which is the right call for its complexity level. Only the read-only/no-side-effect confirmation and any sibling routing are missing.

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?

The tool takes no parameters, so there are no argument semantics to document and the baseline of 4 applies. The description correctly implies a trivial no-argument call rather than suggesting any filter or input.

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 names a specific resource (the Roofing Quotes UK dataset) and enumerates exactly what it returns: columns, numeric flags, row count, and the provenance banner. It is clear but does not explicitly contrast itself with near neighbours like dataset_stats or dataset_provenance, which also surface dataset-level metadata.

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?

"Call this first to learn the schema" gives an explicit ordering instruction and a purpose, which is genuine when-to-use guidance. It stops short of naming an alternative or a when-not-to-use condition (e.g. use dataset_row for value-level detail), so it falls just below the top band.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose one important trait — rows are returned 'in the order given' — but says nothing about read-only safety, lack of side effects, permissions, pagination, or the 2–10 value constraint, leaving key operational behavior undisclosed.

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 definition is a single sentence with the operation front-loaded and no filler. It is appropriately sized for a simple two-parameter tool, though its terseness contributes to the semantic gaps noted elsewhere.

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?

With no output schema and no annotations, the description should explain return shape, matching semantics, and constraints such as the 2–10 value limit. Instead it gives only a compact summary, so an agent lacks enough information to call the tool confidently in edge cases.

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%, so the description must fully explain the two parameters. It conceptually maps 'column' and 'values' ('whose column is any of the given values'), which adds some meaning, but it never explains that column should be a dataset column name or that values are exact-match strings capped at 10 items, leaving substantial ambiguity.

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 specific retrieval operation on a named dataset: rows whose column matches any given value, ordered as specified, aimed at 'X vs Y' questions. It is clear enough to distinguish comparison-by-equality from a general free-text search, though it does not explicitly name or rule out sibling tools such as dataset_search.

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 phrase 'for X vs Y questions' gives implied usage context: it is meant for side-by-side comparison of specific values. However, it offers no explicit when-not guidance and never names an alternative sibling (e.g. dataset_search for text matching or dataset_row for single-row retrieval), so the agent must infer boundaries.

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

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

No annotations are provided, but this is a zero-parameter metadata read, so the mutation/permission burden is minimal. The description usefully discloses the shape of the response (source, date, licence, citation), which matters because there is no output schema.

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?

Two short sentences, front-loaded with the resource and its returned fields, closing with the actionable usage cue. No filler.

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 no-argument metadata lookup with no output schema, the description covers everything needed: what it describes, what fields come back, and when to call it. Nothing relevant is missing.

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?

The tool takes no parameters, so there are no semantics to convey; baseline 4 applies. Schema coverage is trivially 100% on an empty object.

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 resource (the Roofing Quotes UK dataset) and enumerates exactly what it returns: source, computation date, licence, citation. It is clearly distinct from siblings like dataset_stats or dataset_columns, though it never names an alternative explicitly.

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?

"Read this to attribute a figure correctly" gives a concrete when-to-use condition (citation/attribution). No when-not or alternative tool is named, but the purpose is narrow enough that misuse is unlikely.

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

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

With no annotations, the description carries the full burden. It usefully discloses that matching is case-insensitive and exact, but says nothing about whether multiple rows can come back, ordering, limits, or pagination behavior for a lookup 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?

A single sentence with no wasted words, front-loading the dataset and the match condition. It is lean to the point of being slightly under-specified rather than padded.

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, no annotations, and 0% parameter coverage mean the description is the only source of truth — yet it omits what is returned (row set? single row?), how many, and in what order. For a lookup tool with two required parameters, that is a meaningful gap.

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%, so the description must compensate, and it does explain the comparison semantics that the schema leaves out (exact equality, case-insensitive). However, it says nothing about the format or constraints of 'column' and 'value' strings beyond that.

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 — returning the rows of the Roofing Quotes UK dataset that match an exact key — and pins down the dataset by name. The 'equals a value exactly' phrasing implicitly separates it from dataset_search, but no sibling is named explicitly.

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?

There is no when-to-use or when-not-to-use guidance and no alternative named. An agent must infer from the word 'exactly' that this is the exact-match path and dataset_search is the fuzzy path, which is a reasonable but unstated inference.

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

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

With no annotations, the description must carry the behavioral burden. It usefully discloses case-insensitive matching and a hard result cap of 50, which are real behavioral traits, but says nothing about permissions, whether match ordering is deterministic, or what happens with zero matches.

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?

A single front-loaded sentence with no filler: resource, match semantics, and result cap in one pass. Nothing could be removed without losing 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?

For a search tool with no output schema, the definition is minimally viable but leaves the row shape and result ordering unexplained. The two-parameter surface is simple enough that the gaps are tolerable, but a search tool benefits from stating what a returned row contains.

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 coverage is only 50% (the limit parameter has no schema description), and the description compensates by explaining that limit means 'up to 50' and that query matches any cell case-insensitively. It adds genuine meaning beyond the schema for the undocumented parameter, though it omits the minimum of 1.

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 names a specific verb (search), the exact resource (rows of the Roofing Quotes UK dataset), the matching rule (cells contain the query, case-insensitive), and the cap (up to 50). It clearly distinguishes from siblings like dataset_row or dataset_top by being a text-match search, though it never names those alternatives explicitly.

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?

Usage is only implied: an agent can infer this is the tool for locating rows by text content. There is no statement of when to prefer it over dataset_top, dataset_compare, or dataset_row, and no prerequisites or exclusions are given.

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

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

With no annotations provided, the description carries the full behavioral burden, and it does disclose meaningful traits: grouping commas and currency symbols are handled during parsing, and non-numeric rows are excluded and counted rather than silently dropped. It does not cover permissions, pagination, or result shape beyond the metric list, which keeps it from a 5.

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?

A single sentence that front-loads the concrete outputs and folds edge-case behavior into one compact parenthetical. Efficient, though the parenthetical is dense enough that it reads as a run-on.

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?

With no output schema and no annotations, the description does list the returned metrics and the parsing edge cases, covering the main gaps. It omits the required format of the column argument, which is the one thing an agent must get right to call the tool.

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% and the single required 'column' parameter has no documented format (name vs. index, case sensitivity, quoting). The description only implies the column must be numeric; it adds no syntax or format detail the schema lacks.

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 names the resource (a numeric column of the Roofing Quotes UK dataset) and enumerates exactly what is computed (count, min, max, mean, median, sum), so an agent knows precisely what the tool produces. It does not explicitly contrast itself with siblings like dataset_top or dataset_compare, so it stops short of a 5.

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?

There is no when-to-use or when-not-to-use guidance, and no sibling tool is mentioned as an alternative. The phrase 'of a numeric column' hints at the input constraint but does not tell the agent when this tool is preferable to dataset_top, dataset_compare, or dataset_row.

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

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

With no annotations, the description carries the full behavioral burden. It implies a read-only ranking operation, which is useful, but says nothing about the schema's 50-row cap, what happens when a non-numeric column is passed, ordering ties, or the shape of the returned rows.

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?

A single compact sentence that front-loads the operation and the dataset scope. The trailing parenthetical example is slightly cryptic and the sentence reads as a fragment, but there is no filler.

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 top-N read tool with no output schema and no annotations, the description covers the core ranking behavior but omits the limit parameter, the 50-row maximum, and the return shape. Enough to call it roughly correctly, not enough to call it confidently.

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 coverage is only 33% (only `ascending` is documented in the schema). The description partially compensates by establishing that `column` selects the ranking key, that it must be numeric, and that direction is highest-by-default / lowest-on-request, but it entirely omits the `limit` parameter and its 1-50 bound.

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 gives a specific operation (return the highest/lowest rows of the Roofing Quotes UK dataset ranked by a numeric column) plus an intent framing ('which is the most/least X'). It is clear what the tool does, but never names or distinguishes itself from siblings like dataset_row or dataset_search, which also surface row data.

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?

There is no statement of when to use this tool versus dataset_row, dataset_stats, or dataset_search, no prerequisites (e.g. the column must be numeric), and no exclusions. The 'most/least X' phrasing hints at a ranking use case but gives no actionable routing guidance.

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

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

With no annotations, the description carries the full burden, and it does disclose meaningful behavioral facts: nothing is bought, ordered or paid, no quote is guaranteed, and the interaction is free. It also previews what is returned (recipients, consent wording, confirmation method). It stops short of stating anything about the describe call's own side effects or access requirements, which keeps it from a 5.

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, front-loaded with the imperative 'Read first', then the substance, then the return contents. No sentence is filler and the most decision-relevant fact (it is not a purchase) appears early.

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 zero-parameter documentation tool with no output schema, the description covers what the tool yields and the key non-financial guarantees, which is most of what an agent needs. It could be slightly more complete by naming the exact fields/consent text returned or clarifying that the call itself has no side effects, but nothing critical is missing.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The description correctly implies the tool is invoked without arguments and just returns explanatory content.

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 makes it clear this is a read-only informational tool ('Read first', 'States plainly what submit_enquiry does'), and it explicitly contrasts the enquiry with a purchase or guaranteed quote. However, it frames itself largely around submit_enquiry's behavior, so the tool's own identity as the describer of the enquiry flow is inferred rather than stated with a crisp verb+resource for enquiry_describe itself.

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?

'Read first' gives a clear ordering hint that this should be consulted before engaging the enquiry flow. Beyond that, there is no explicit when-not-to-use guidance and no named alternative (e.g., enquiry_fields) to help the agent choose between the two sibling enquiry tools.

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

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

With no annotations, the description carries the full burden and does reasonably well: it discloses the complete shape of what is returned, including conditional content ('the allowed options where there are any'), and ties the result to a downstream write via submit_enquiry. It never explicitly states this is a read-only, no-side-effect lookup, which is the main remaining gap.

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?

Two sentences, zero filler. The colon-list enumerates the returned properties compactly and the usage hint is the final sentence, so the payload is front-loaded.

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 parameterless lookup with no output schema, the description effectively substitutes for the missing return documentation by naming every property of a field. The only omission is the concrete return container (a list vs. a keyed map), so the agent must infer structure.

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?

The tool takes zero parameters, so per the baseline there is nothing for the description to document. The only reference to an argument is the usage hint about keying answers by field key when calling submit_enquiry, which is helpful but belongs to a different tool.

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?

Names a specific resource (the Roofing Quotes UK enquiry fields) and enumerates exactly what each field carries (key, label, type, required, help text, options), so the agent knows this is a schema/introspection tool rather than a data-search tool. It stops short of explicitly distinguishing itself from the similarly named sibling enquiry_describe, which leaves a small ambiguity.

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?

Gives a concrete downstream workflow: fetch the fields here, then pass answers to submit_enquiry keyed by field key. That is genuinely actionable 'when to use' context. It does not state exclusions or contrast against enquiry_describe, so it stops short of a 5.

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

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

With no annotations, the description carries the full load and does it well: it discloses the auth requirement (Authorization: Bearer), a rate/quota constraint ('metered per key per day'), and graceful unauthenticated behavior ('without a key the answer says how to get one'). It stops short of describing pagination termination or how the caller knows it has reached the last page.

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 tight sentences, front-loaded with the resource and paging, followed by auth/quota and no-key fallback. Every sentence earns its place, though 'the answer says how to get one' is slightly loose phrasing.

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?

With no annotations, no output schema, and 0% schema description coverage, the description does a fair amount of work (scope, auth, quota, fallback) but leaves two gaps an agent would want closed: how pagination ends and what a page's payload/provenance actually contains.

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 coverage is 0%, so the description must compensate. '200 a page' usefully conveys the intended pageSize chunk (schema allows 1-200) and 'in pages' implies the page parameter, but defaults, page numbering (1-based), and the relationship between page and pageSize are left unstated.

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 specific resource ('every entity of Roofing Quotes UK register') and mode ('in pages, 200 a page, with provenance'), which is enough to distinguish a full-register dump from the filtering siblings (entities_search, entities_in). It does not explicitly name those siblings, so the differentiation is inferred rather than stated.

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?

Usage is implied rather than stated: 'every entity' signals bulk export as opposed to the filtered lookups offered by entities_search/entity_lookup, and the auth prerequisite is given. There is no explicit when-to-use/when-not statement or named alternative, so guidance stays at the implied level.

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

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

With no annotations, the description carries the full burden, and it does disclose pagination behavior ('50 a page'). However, it says nothing about result ordering, how to page beyond the first set, total counts, or authentication/permission requirements, leaving meaningful gaps.

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?

A single dense sentence with no wasted words, front-loading the resource and region scope before the optional filter and page size.

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 4-parameter tool with 0% schema coverage and no annotations or output schema, the description covers region and service but leaves page/pageSize semantics and return shape unexplained. Adequate but with clear 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 0%, so the description must compensate. It adds real meaning for 'region' (a state or jurisdiction, accepted by id or name) and clarifies 'service' is optional, but says nothing about page/pageSize beyond the ambiguous '50 a page' hint.

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 concrete resource and scope: entities in one region of the Roofing Quotes UK register, with an optional service filter. The garbled phrasing ('The Roofing Quotes UK register entities in one region') lacks a clean verb, but the region-scoping distinguishes it from siblings like entities_search and entities_export.

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?

No when-to-use or when-not-to-use guidance is given, and no alternatives are named. The agent must infer that this tool is for enumerating all entities in a region, with no hint about how it relates to entities_search or entities_export.

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

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

With no annotations, the description carries the full burden, and it does describe the informational, read-only payload (register shape, counts, identifier schemes, citation). It omits any note about caching, freshness of the counts, or that the response is a metadata blob rather than entity records — the main residual risk for a zero-param discovery call. The awkward "register register" repetition slightly muddies the register it refers to.

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 content list is front-loaded and the call-to-action is a short imperative sentence at the end, which is the right position for an ordering hint. The single long enumerative sentence is dense and the duplicated "register register" is sloppy, but nothing is padding.

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 or annotations exist, so the description must convey return content, and it does enumerate the main buckets (fields, counts, regions, services, identifier schemes, citation). For a simple metadata tool this is nearly sufficient; it just doesn't hint at the structure of the return or how large it is, which matters since there is no output schema.

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?

The tool takes zero parameters, so the schema has nothing to explain and the baseline is 4. The description correctly implies no filtering or argument is needed to obtain the register-wide overview.

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 names the resource (the Roofing Quotes UK register) and enumerates the concrete content an agent gets back: fields, entity counts, regions, services, identifier schemes, and citation guidance. That is specific enough to distinguish it from entity_lookup or entities_search. It does not, however, explicitly separate itself from siblings with overlapping scope such as dataset_columns, dataset_stats, and dataset_provenance, which also surface fields, counts, and citation data.

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?

"Call this first." is a direct, actionable ordering instruction that tells the agent when this tool belongs in a workflow. There is no statement of when NOT to use it or which sibling to prefer for a narrower need (e.g. dataset_columns for a field list alone), so it stops short of full routing guidance.

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

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

With no annotations, the description carries the full burden. It usefully discloses that results are capped at 50 rows and which fields the query matches, but says nothing about permissions, ordering, default limit, pagination, or return shape beyond the row count.

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?

A single dense sentence that is front-loaded with the resource and fields, ending with the result cap. It wastes no words, though packing every detail into one sentence slightly reduces scannability.

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 four-parameter search tool with no annotations and no output schema, the description covers matching fields, filter formats, and the row cap, but omits what the returned rows contain and pagination behavior. It is adequate but leaves clear 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 coverage is 0%, so the description must compensate. It adds real meaning for region (accepts id or name) and service (accepts slug or name), and ties q to a set of searchable fields, but leaves limit semantics largely to the schema's min/max and does not explain the default.

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 specific verb (search) and resource (entities of the Roofing Quotes UK register) and enumerates the searchable fields, so an agent knows exactly what it queries. It does not explicitly differentiate itself from sibling tools like entity_lookup or entities_in, which is the main gap.

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 never says when to use this tool versus alternatives such as entity_lookup, entities_in, or entities_export. The optional region/service filters imply some scoping, but there is no explicit when-to-use or when-not-to-use guidance.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses an exact-match lookup and that the full record plus page is returned, but it omits error behavior when no match is found, authentication needs, and the meaning of 'page'.

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 two tight sentences with zero waste. The primary action and lookup key are front-loaded before the return behavior.

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?

Given no annotations and no output schema, the description should do more. It states the return is the whole record with its page, but it does not describe the record structure, error cases, or how the three optional parameters interact, leaving important gaps for correct invocation.

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 only 33%, and the description adds meaningful semantics by explaining that the identifier is a combination of scheme and value (e.g. lei) or alternatively a slug. However, it does not clarify mutual exclusivity, precedence, or required-use conditions for the three optional parameters.

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 clearly states what the tool does: fetch the register entry for a firm by identifier or slug. It distinguishes from a search tool by stating 'Exact match' and 'returns the whole record with its page,' though it does not name or contrast with sibling tools like entities_search explicitly.

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 when to use it (when you already have an exact identifier or slug), but it does not provide explicit when-to-use guidance versus alternatives such as entities_search, nor does it state prerequisites or exclusions.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the two-step validate-then-submit flow, the return of a summary/consent line/confirmation token, and the post-submission email-link gate that must be clicked before any provider sees the data. That is exactly the behavioral context an agent needs before mutating state.

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-loads the purpose and the not-a-purchase caveat, then walks the two steps in order. It is long but nearly every clause carries operational weight; the only redundancy is restating the consent sentence that also appears in the schema.

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 nested-object, two-phase mutation with no output schema, the description covers the inputs, the intermediate return artifacts, the confirmation loop, and the downstream email-verification effect. Nothing needed to invoke it correctly is missing.

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 coverage is 100%, so the baseline is 3, but the description adds real meaning: answers must be keyed by field key from enquiry_fields, and confirmation is the token returned in step 1 after the person approves the summary. It does not add much beyond that, so 4 rather than 5.

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+resource (submits an enquiry to Roofing Quotes UK) and immediately disambiguates what it is not ('NOT a purchase, NOT a guaranteed quote'). It also routes the agent to the enquiry_fields sibling as the source of field keys, so the submit/discover split is clear.

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?

Gives explicit, ordered when-to-call instructions for both invocations, including the gating condition ('only if the person agrees') and the required consent=true. The not-a-purchase framing covers the main when-not case an agent would otherwise confuse.

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