DataScoop public data

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuine behavioral value beyond that: it discloses that the return payload includes pricing tiers, signup URLs, and API-key-passing instructions plus ready-made user-facing wording.

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 whose content list is dense but each item earns its place by signalling what comes back. It is slightly run-on but contains 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?

With no output schema and no parameters, the description carries the burden of describing the return contents, which it does by enumerating plan, caps, prices, URLs, and API-key wording. Slightly more on the exact response shape or whether plans are per-connection would make it fully self-sufficient.

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 baseline is 4 and there is nothing for the description to clarify about inputs.

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 concrete resource (access/pricing info for this connection) and enumerates its contents: current plan, row caps, prices, URLs, API-key instructions, and user-facing wording. It is clearly distinct from the dataset-querying siblings, though the opening phrase 'How to get full access' frames it as advice rather than stating the purpose outright.

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: the mention of row caps and 'telling a user how to get every row' suggests it should be called when a user hits limits or asks about upgrading. There is no explicit when-to-use statement, no alternative named, and no prerequisites described.

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?

The annotations already establish that this is a safe, idempotent, closed-world read. The description adds context that the annotations do not cover: the data is free, breakdowns differ by dataset type (rating shares vs construction/demolition categories vs record counts), dates appear only when published, and the page URL returned must be cited. It omits rate limits and pagination, but the additional behavioral and data-quality caveats are useful.

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?

Four sentences, each carrying information: coverage, per-dataset breakdown semantics, how to omit area, and the caveat plus citation. The dataset enumeration is somewhat list-heavy but is front-loaded and directly relevant to coverage expectations.

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 only two parameters, no output schema, and full annotation coverage, the definition needs to explain return-value shape and variability. It does this by describing rating shares, type breakdowns, record counts, and dates, and by warning the agent to read field names and coverage first. It does not say what happens on an unknown area or dataset, which is the only material 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 coverage is 100%, so the schema already documents both parameters, including the 'omit to list areas' behavior and the dataset id examples. The description reinforces that behavior and adds the dataset families, but adds no syntax, format, or slug details beyond the schema. A baseline of 3 is appropriate.

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 and resource (area totals and breakdowns) and spells out the dataset families covered, e.g. CQC care-home lists, food hygiene ratings, building permits. It does not, however, name the sibling tool query_dataset, or explain how it differs, so an agent must infer the boundary from context.

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 gives parameter-level guidance: 'Omit area to list the areas available', and the caution to 'read the returned field names and coverage before comparing areas'. It never states when to pick this tool rather than query_dataset or get_dataset_schema, so the choice among siblings is left to 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?

Goes well beyond the annotations (readOnly/idempotent/non-destructive) by disclosing the 25-provider truncation cap, an async 'pending response requires retrying after the supplied delay' pattern, and the important semantic caveat that provider IDs are registered operators, not ultimate owners. These are exactly the traits an agent cannot get from structured fields.

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 the purpose and output inventory, then caveats and defaults. Semicolon-packed run-on sentences are dense but every clause carries distinct information; nothing is 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?

No output schema exists, so the description carries the return-value burden and does so by enumerating the response components and the 25-item cap, plus the pending/retry protocol. Slightly incomplete in that it does not describe what fields a provider summary contains, but the shape is clear enough to call correctly.

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%, but the description compensates by stating that careHome defaults to true and that the filters object follows the same strict semantics as query_dataset. The remaining detail (filter keys come from get_dataset_schema, case-insensitivity) lives in the schema description rather than the tool description, hence not a 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?

Names a specific verb (return) and resource (CQC care-home territory intelligence) and enumerates exactly what comes back: selection totals, providers, beds, coverage, up to 25 summaries. It implicitly contrasts with query_dataset (aggregates/summaries vs. presumably row-level results) but never states the contrast explicitly, so the agent must infer sibling differentiation.

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 context is implied rather than stated: it says it uses 'the same strict filters as query_dataset' and notes careHome defaults to true, which hints at when it applies. There is no explicit 'use this when you want aggregate counts instead of rows' or 'use query_dataset instead when...' routing guidance, and no prerequisites are named.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds that the tool returns both columns and filters, which is useful but not a significant behavioral disclosure beyond what the schema hints. No contradictions.

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, no fluff. The key information (what it does, and the critical usage note about filter keys) is front-loaded and every word earns its place.

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 single-parameter read-only tool with full schema coverage and no output schema, the description is nearly complete. It lacks an explicit mention of the output format, but the description of 'columns' and 'filters' suffices. Could be a 5, but the lack of output details is a minor 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?

The only parameter 'dataset' is fully described in the schema with examples, so schema coverage is 100%. The description does not add any extra parameter-specific information beyond what is in the schema, but given full coverage this is adequate.

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 the tool retrieves a dataset's columns and accepted filters, which is specific and distinct from siblings like query_dataset and list_datasets. It names the resource type (dataset) and the exact information returned.

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 explicitly instructs to use filter keys rather than column names when calling query_dataset, providing a clear when-to-use and a corrective note for a common mistake. It also implies query_dataset is the next step after getting the schema.

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?

The annotations already establish that this is read-only, idempotent, and non-destructive. The description adds useful behavioral context beyond those annotations by stating that the tool returns every dataset in the catalog and specifying exactly what information is included, plus noting that the catalog grows over time.

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 front-loaded with the core action and scope, and the parenthetical list of datasets is informative rather than padding. The final sentence adds useful workflow guidance. It is slightly dense due to the long enumeration, but every part contributes.

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?

Despite having no output schema, the description clearly states the return fields and scope, and the optional filter is documented in the input schema. The tool is simple (one optional parameter, no required arguments), and the description supplies enough context for correct first-time 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?

The schema fully documents the single optional 'country' parameter with an ISO 3166-1 alpha-2 description, so schema coverage is 100%. The tool description does not add parameter-specific guidance, but it does not need to; the baseline applies.

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 uses a specific verb and resource: 'List every dataset DataScoop carries', and enumerates the dataset categories. It also names the return fields (country, coverage, row count, licence, refresh date, page URLs), making the tool's purpose unmistakable and distinct from siblings like search_datasets.

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 gives clear entry-point guidance: 'Call this or search_datasets first.' This situates the tool in a workflow and names the main sibling alternative, though it does not explicitly explain when to prefer one over the other.

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?

The description adds substantial behavioral context beyond the annotations: personal fields are excluded, published business identifiers may still identify sole traders, free calls cap at 25 rows, truncation sets truncated=true with a next_step, and Pro calls support up to 1,000 rows with offset paging. These details materially affect safe and correct use.

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 front-loaded with the return contract and then packs privacy, plan limits, paging, and format guidance into a few dense but well-structured sentences. No sentence is wasted.

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 read-only query tool with six parameters, a nested filter object, and no output schema, the description covers return shape, privacy caveats, plan-based caps, truncation, paging, and summary mode. It gives an agent enough to call the tool correctly without needing more explanation.

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 schema already documents limit, format, offset, dataset, filters, and strict_filters. The description reinforces plan caps and summary format but adds only marginal parameter-level meaning beyond the schema, particularly around truncation behavior.

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 and resource: returning matching public records with total count and citation attribution. It clearly identifies this as the record-querying tool, which is distinct from siblings like list_datasets or get_dataset_schema, though it does not explicitly name those alternatives.

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 through the free/Pro row limits, truncation behavior, and the option to request a summary, but there is no explicit guidance on when to choose this tool over siblings such as search_datasets or get_dataset_schema. An agent can infer it is for querying records, but routing guidance is limited.

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?

The annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior. The description adds useful context beyond annotations by explaining that candidates are declared coverage, not verified matches, and that downstream filters are not inferable from the original request.

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 front-loaded with the core purpose, followed by an important caveat about candidate quality and a concise next-step instruction. Every sentence carries useful information without repetition.

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 two-parameter search tool with full schema coverage and rich annotations, the description provides the key caveat and follow-up path an agent needs. It does not describe result shape or pagination, but with no output schema this is a minor gap rather than a blocking omission.

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 both parameters are already documented. The description adds some meaning to the query parameter by giving examples of keywords or short task descriptions, but it does not explain the optional country parameter or add syntax beyond the schema.

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 and resource: finding candidate DataScoop datasets from keywords or a task description. It also clarifies that results reflect declared coverage rather than verified matches. It is clear, but it does not explicitly distinguish itself from the sibling list_datasets tool.

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 gives a clear follow-up workflow: call get_dataset_schema, then query_dataset with explicit filters. It also warns that example filters are not inferred from the request. It does not state when not to use this tool or compare it directly with list_datasets.

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