gankdat

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

Goes well beyond the annotations (readOnly=false, openWorld=false, idempotent=false, destructive=false) by disclosing the return value (a PayPal approval link), the required human approval step on PayPal's page, a security instruction (never paste card details into the chat), the downstream confirm_credit_purchase call, and billing semantics (packs spent after the monthly allowance, never expire). This is rich, non-redundant behavioral context.

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 action and pricing, then the flow, then constraints; every sentence carries distinct information. It is on the dense side with semicolon-chained clauses, 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 exists, so the description carries the return-value burden and does so by naming the PayPal approval link. Combined with the approval flow, cost, sandbox caveat, and account prerequisite, an agent has everything needed to invoke and follow through 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 100% and the enum values are fairly self-describing, so the baseline is 3. The description adds real meaning beyond the raw enum by mapping each pack to its credit quantity and US dollar price, which helps the agent choose the right 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?

States a specific verb (buy) and resource (credit pack) and enumerates exactly which packs exist with their credit amounts and prices, so the agent knows the scope without opening the schema. It is clearly distinguishable from the sibling confirm_credit_purchase, which it explicitly routes to as the follow-up step.

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 clear operational context: this is a one-off purchase for the signed-in account, it is sandbox/test money, it is free to call, and the user must approve on PayPal before calling confirm_credit_purchase. It stops short of stating an explicit when-not-to-use condition, but the sandbox constraint and the required follow-up step make the usage context unambiguous.

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 declare readOnlyHint=false and idempotentHint=false, and the description adds real context beyond them: the operation is a poll that returns "pending" until approval, the key is issued "exactly once", and the call is free/no-auth. What it omits is what happens on a second claim attempt or whether the claim_secret expires.

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 dense sentences, front-loaded with the triggering condition, then the return behavior, then the downstream auth usage. Every sentence carries information an agent needs.

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?

The description fully covers the aspect an output schema would otherwise supply (the pending/approved states and the key), which is strong. But with no output schema, two undocumented required parameters, and no note on retrieval failure or expiry, it is only barely sufficient 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 0% and the description never mentions request_id or claim_secret, so an agent gets no hint about what these required strings are or where they come from (presumably request_api_key's response). With low coverage the description should compensate, and it does not.

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 (poll/claim) and resource (the API key) and explicitly positions itself relative to request_api_key, the sibling an agent would otherwise confuse it with. There is no ambiguity about what the tool does.

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?

"Poll after request_api_key" gives a clear precondition and sequencing relative to the sibling, and the pending/approved outcomes tell the agent how to interpret results. It stops short of explicit polling cadence or give-up conditions, so it is not quite 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?

The description adds real behavioral context the annotations don't: cost ('Free to call'), an auth requirement (user's account), and the resulting mutation (credits added, new balance returned). However, 'Safe to repeat — an order is captured at most once' asserts at-most-once effect on repeat calls, which conflicts with the declared idempotentHint=false, so the behavioral disclosure is partially self-contradictory.

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 action and the trigger condition, with no filler. The trailing fragment 'needs the user's account' is terse to the point of vagueness, which costs it the top mark.

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 one-parameter mutation with no output schema, the description covers trigger, effect (credits added), return value (new balance), cost, and auth. What it leaves undefined is the second-call outcome (error vs. identical response), which matters given the idempotency claim.

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?

Only one parameter and schema description coverage is 100%, and the schema already documents order_id as 'returned by buy_credits'. The description reinforces the buy_credits provenance but adds no syntax, format, or validation detail beyond the schema, so the baseline 3 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 states a specific verb and resource: capturing an approved PayPal order and adding pack credits to the account. It also makes the distinction from the sibling buy_credits explicit by tying itself to the post-approval step, so an agent can tell the two apart without opening either schema.

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?

It gives a clear trigger ('After the user approves the buy_credits link on PayPal') and a prerequisite ('needs the user's account'), which routes the agent correctly relative to buy_credits. It stops short of an explicit when-not rule, but the sequencing is unambiguous.

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 establish readOnlyHint, idempotentHint, and destructiveHint=false, but the description adds real behavioral value beyond them: it discloses that other tools return full pages and account credits afterward, that it returns the plan and usage, and that it is free. It stops short of covering token lifetime, revocation, or what happens if sign-in fails.

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 core action and effect, then the fallback paths. The x402 URL clause is dense but earn its place as an alternative channel; the account/credits contrast is stated twice in essence, which slightly inflates length.

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 covers everything an agent needs: what it does, its side effect on sibling tools, a summary of its return value, cost, and two alternatives for the no-account case. Nothing material 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?

There are zero input parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate. The mention of email is directed at the sibling request_api_key, not at this tool's own 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?

States a specific verb and resource (connect the user's gankdat account) plus the mechanism (OAuth sign-in prompt). It distinguishes itself from siblings by explaining the downstream effect (full pages + credits instead of preview) and names request_api_key as the alternative path.

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?

Explicit when-to-use and when-not-to-use: use this when a person can complete an OAuth sign-in; when no person is available, use request_api_key or the x402 pay-per-call endpoint. The alternative and its selecting condition are both 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 readOnly/idempotent/non-destructive, so the bar is lower, and the description adds real context beyond them: 90-day history, newest-first ordering, 1 credit per call, and an unauthenticated preview capped at 5 rows and 20 calls/day. It stops short of describing pagination interaction with the preview cap, but the operational constraints are unusually well disclosed.

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 tool returns before the operational details, and every clause carries information (cost, limits, filter syntax). The inline source enumeration is long but necessary for disambiguation, so it earns its space.

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 low schema coverage, the description supplies the return semantics (delta rows, newest first) plus cost and rate limits. It is close to self-sufficient for a 6-param tool, with only per-parameter details for page/per_page/change left to the schema enums.

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 17%, so the description must carry the load, and it does for the hardest parameter: `filter` is explained as the source's own query params applied to the changed record, with a worked example and a pointer to list_sources supported_params. `source` values and the 90-day `since` window are implied, but page/per_page/change remain undocumented beyond their enums.

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: 'Rows added, removed or changed between daily refreshes of a register dataset', then enumerates the exact datasets. It is immediately distinguishable from the sibling query_* tools, which read a whole register rather than a delta.

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?

Explicitly instructs 'Poll this instead of re-reading a whole register', naming the alternative behavior (full-register query tools) and the condition that selects this tool. The filter example shows a concrete polling use case, removing nearly all 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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context: the call is free of charge and its output branches on whether an API key is presented. That auth-dependent branching is exactly what annotations cannot express.

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 front-loads what is returned, then the key-dependent branch, then the cost note. Every clause carries information and 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 zero-parameter read with no output schema and full annotation coverage, the description covers what is returned, the two behavioral cases, and cost. Minor gaps around the shape of the returned values are acceptable since annotations already carry the safety profile.

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?

There are no parameters, so the baseline is 4. The description correctly conveys that behavior is driven by the ambient API key rather than any argument, which the empty schema cannot express on its own.

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 exact resource returned (plan, credits used/granted/remaining) and the conditional case without a key. It is clearly distinct from sibling auth tools like claim_api_key and request_api_key, which manage keys rather than report usage. It stops short of a 5 only because it doesn't explicitly frame itself against any alternative.

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?

It implies the two usage contexts: with a presented API key versus without one (preview calls left today). It does not state when to call this versus checking usage elsewhere or mention any rate limits around the preview. The guidance is implied rather than explicit.

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 readOnly, idempotent, non-destructive behavior, but the description adds information annotations do not carry: the cost profile ('Free to call') and the shape of what is returned (dataset entries with tool names and filter params). With no output schema, that return-value disclosure is genuinely 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?

Two short sentences, front-loaded with what the tool returns, and nothing wasted. Well-sized for a zero-parameter discovery tool.

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-param, no-output-schema listing tool, the description covers what it returns and that it is free, which is enough to invoke it correctly. It could go further by telling the agent this is the discovery step preceding the query_* tools, but the essentials are present.

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; there are no parameter semantics for the description to add or omit.

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 ('datasets this API serves') and what it returns ('tool name and filter params for each'), which implicitly distinguishes it from the query_* siblings as the discovery entry point. It does not name a sibling explicitly, 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?

'Free to call' implies it can be invoked freely and suggests it's a cheap discovery step, but there is no explicit when-to-use guidance or direction to call it before the query_* tools. Usage is implied rather than stated.

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 tell the agent this is a read-only, idempotent, non-destructive, open-world query. The description adds meaningful non-annotation context: the credit cost model, the preview truncation (up to 5 rows, 20 calls/day without a key), and the Blind Mode ingestion limit. It does not disclose pagination behavior beyond the default, but the pricing and Blind Mode disclosures carry real operational value.

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 dense, front-loaded sentences with no filler. The content is information-rich, though the sentence combining source description, field list, Blind Mode, AND semantics, and pricing in one block could be split for 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 complex 16-parameter query tool with no output schema and no annotation coverage of parameters, the description is moderately complete: it covers data source, fields, pricing, and the Blind Mode caveat. But it leaves parameter behavior, pagination, and result shape unaddressed, which matters for such a broad filter surface.

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 carry parameter semantics, but it only gestures at them ('filters combine with AND; q searches all text fields'). It does not explain the 16 parameters individually — CPV codes, notice_type, procedure_type, contract_nature, places_of_performance, and the date range params are all undocumented in both schema and description. This leaves significant gaps for a 16-param 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?

The description specifies a concrete verb and resource ('Contract notices and awards from TED'), names the data source (the official EU procurement journal), and enumerates the fields returned (buyer, country, CPV codes, values, deadlines). This makes it easy to distinguish from sibling tools like query_uk_tenders that cover a different jurisdiction.

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 through 'filters combine with AND' and the Blind Mode note, but provides no explicit when-to-use or when-not-to-use guidance relative to siblings. An agent has to infer that this is the EU-jurisdiction procurement tool vs. the UK-specific ones.

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 readOnly/idempotent annotations: provenance (official nightly ODS extracts), keying by stable ODS code, explicit data exclusions (telephone numbers dropped, practitioner files never ingested), and the 5-row/20-call preview behaviour. This is exactly the kind of context annotations cannot carry.

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 what the register contains, then provenance, then filter/pricing mechanics — every clause carries information. The second and third sentences are dense run-ons, but nothing is redundant 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 and no annotation-level semantics, so the description correctly carries the dataset shape, exclusions, and auth/cost model. It falls short only on the remaining undocumented filter parameters and explicit pagination behaviour, which an agent would need to guess.

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?

With 18 parameters and 0% schema description coverage, the description must carry the burden. It maps many filters (q, name, status, ods_code, org_type, parent_code, postcode, dates, prescribing_setting) but leaves town, outward_code, health_geography, national_grouping, page and per_page unexplained, and does not disambiguate the open/close before-vs-after date axes.

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 (the NHS ODS register for England) and enumerates exactly what entities and fields it covers, from ODS code to parent organisation. Its scope is unmistakable against siblings like query_uk_care_locations or query_uk_charities without opening any schema.

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 filters combine (AND), what q does (searches all text fields), credit cost per call, and the unauthenticated preview limit — all genuinely useful invocation context. It never names an alternative tool or states when not to use this one, 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?

Beyond the annotations (read-only, idempotent), it discloses ingest-time behavior (addresses, SSN/TIN/NPI, and free-text comments dropped), filter combination logic (AND), the broad-search parameter, and a cost model including the unauthenticated preview cap of 5 rows/20 calls per day. These are precisely the operational facts an agent needs before calling.

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?

One dense but well-ordered paragraph that front-loads what the dataset is, then normalization guarantees, then filter semantics, then cost. No filler sentences, though the run-on structure requires careful reading.

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 search tool with no output schema and annotations covering safety, the coverage of sourcing, normalization, filter logic, and pricing is good. However the parameter surface is largely unexplained, leaving a meaningful gap for a 15-parameter filter 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?

With 15 parameters and 0% schema description coverage, the description carries the full burden, yet it only explains 'q searches all text fields' and that filters combine with AND. Key filters such as uei_sam, cage_code, classification, exclusion_type, and the four date bounds are left undocumented in both schema and description.

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+scope: 'Every active exclusion (debarment) on the official US SAM.gov list', enumerating entity types (individuals, firms, special entities, vessels) and fields returned. This is unambiguously distinct from the many query_uk_* and query_eu_ted siblings.

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?

Frames the use case clearly ('normalized for supplier due diligence', 'served for compliance purposes'), which tells an agent when this belongs in a workflow. It stops short of explicit when-not guidance or naming an alternative source, but there is no direct sibling covering the same jurisdiction.

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 read-only/idempotent/closed-world, and the description still adds material behavior: phone numbers are dropped at ingest, registered-manager names are never ingested, 1 credit per call with an API key, and a keyless preview capped at 5 rows / 20 calls per day. Cost, rate limits, and data-completeness caveats are exactly the traits annotations cannot express.

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 resource, then result fields, provenance, and caveats — each sentence carries content. It is dense and slightly list-heavy, but there is almost 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?

No output schema exists, so the description compensates by enumerating returned fields and the stable CQC location id key. Cost, quota, and data-exclusion caveats are covered; the main remaining gap is the meaning/format of the pagination and niche filter parameters.

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?

With 15 parameters at 0% schema description coverage the description carries the burden, and it only partly does: it clarifies that q searches all text fields and that filters AND together, and lists filterable facets (service types, specialisms, provider, address, local authority, region, latest check date). It says nothing about the semantics of page, per_page, website_present, outward_code, or the accepted values for specialisms/service_types.

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 (query) plus an exact resource (CQC-regulated health and social care locations in England) and enumerates the entity types covered. It is unmistakably distinct from siblings like query_nhs_ods or query_uk_charities, which target different registries.

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 the tool is used mechanically — 'Filters combine with AND; q searches all text fields' — and gives cost/quota conditions for keyed vs keyless calls. It does not, however, tell the agent when to prefer a sibling (e.g., NHS ODS for organisation reference data), so routing guidance 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial context beyond them: provenance ('official daily public extract'), a privacy boundary of what is never ingested (address lines, phone, email, trustee names), and the billing/preview behavior (1 credit/call, 5-row preview, 20 calls/day). That is exactly the extra agent-relevant behavior structured fields cannot express.

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?

One dense block, but it is front-loaded with dataset scope and the field inventory is compressed into a single readable run-on rather than scattered sentences. Given the breadth of the record, the length is largely earned; it could be tightened but wastes little.

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 23-parameter, no-output-schema tool the description does well on data content, provenance and cost, and correctly avoids re-explaining return values. The gap is that an agent still cannot confidently populate most filter parameters, so the definition is usable but not fully complete.

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% across 23 parameters with no enums, so the description carries the full burden — but it mostly describes returned fields, not input semantics. Only 'q' (searches all text fields) and AND-combining are explained; value conventions for is_cio, gift_aid, website_present, insolvent, in_administration, reporting_status and charity_type are left entirely to guesswork, as are the date-range and income-range pairings.

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?

Opens with a specific verb+resource and an unambiguous scope: 'Every registered and removed charity on the Charity Commission register for England and Wales.' The dataset boundary is unmistakable against siblings like query_uk_companies or query_uk_sanctions without needing to read any schema.

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 clear operational context — 'Filters combine with AND; q searches all text fields' plus the credit cost and the no-key preview cap. It does not explicitly name an alternative tool or a when-not-to-use condition, but the dataset is so distinct from the other query_* siblings that no routing guidance is really needed.

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 readOnly/idempotent/non-destructive, and the description layers on genuinely additive behavior: Blind Mode drops officer/PSC data and address lines in favour of locality/postcode, data refreshes daily, each call costs 1 credit with a key, and keyless use is capped at 5 preview rows and 20 calls/day. These are exactly the operational traits an agent cannot get from the 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?

Three tight sentences with the resource and returned fields front-loaded, followed by privacy scoping and then cost. No filler or repeated annotation restatement; the only slight drag is packing Blind Mode, credits, and rate limits into one long sentence.

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, the description usefully enumerates returned fields and discloses cost/rate limits, which is more than many peers. However, for a 12-parameter tool with zero schema documentation it omits pagination behaviour, sort order, and the semantics of most filters, so an agent still cannot call it precisely beyond q plus AND-combined filters.

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 12 parameters, so the description carries the full burden, yet it only explains that filters combine with AND and that q searches all text fields. It says nothing about status or company_type value domains, sic_codes format, company_number vs company, postal_code/locality matching behaviour, or the date bounds — leaving most parameters ambiguous.

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 (newest companies on the UK register, sourced from the official Companies House API) and enumerates the returned fields, which cleanly separates it from sibling datasets like query_uk_charities or query_uk_insolvency. It stops short of a 5 because the tool name 'query_uk_companies' implies arbitrary UK company search while the description scopes it to newest incorporations only, and no explicit verb frames the operation.

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 guidance and no routing to or away from any sibling tool; an agent is left to infer that this is for browsing recent incorporations rather than querying companies generally. The credit and preview limits are cost context, not usage guidance, and no exclusions or prerequisites are stated.

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: discloses 24-hour caching, Blind Mode semantics (officers and individual PSCs are never ingested; filing events carry category codes not names), per-call credit cost, the no-key preview cap and 20 calls/day limit. These are non-obvious behaviours an agent cannot get from readOnlyHint/idempotentHint.

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 core purpose, then the returned fields, then safety/cost constraints; every sentence carries information. The field enumeration and pricing sentence are dense but not 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?

For a read-only lookup with no output schema, the description thoroughly characterises the payload, privacy behaviour, cost model and rate limits. Its only real gap is the three uninterpreted parameters, which the schema also fails to explain.

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 5 parameters, yet the description only clarifies the single-record key form for company_number and company (e.g. {"company_number":"00000006"}). The q, page and per_page parameters go completely undocumented, and page/per_page sit oddly against 'One record per call,' leaving the agent to guess how they interact.

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 ('One UK company by number or name, live from the official Companies House API') and enumerates exactly what the profile contains (status, SIC codes, charges, filing events, PSCs). The phrase 'One record per call' separates it from the plural list sibling query_uk_companies.

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 usable lookup context ('by number or name', named-key example with company_number) and operational context (24h cache, 1 credit, preview limits without a key), but never states when to prefer this over the neighbouring query_uk_companies or the other UK source tools. Usage is implied rather than prescribed.

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description layers on real behavioral context: daily-refreshed two-week window, organisation-level-only granularity, one row per award/supplier, 1 credit per call, and a 5-row preview capped at 20 calls/day without a key. That is value well beyond the 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?

A single dense paragraph that front-loads what the resource is, then the data scope, then filter semantics, then cost. Every sentence carries information, though the long en-dash field list makes it denser than ideal.

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 15-parameter, no-output-schema read tool, the description covers what is returned, the window, granularity, filter combination semantics, and cost/preview limits. The main remaining gap is pagination behavior for page/per_page, which an agent must infer.

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 15 parameters, so the description carries the burden and largely does: it enumerates the queryable/returned dimensions (buyer, supplier, company number, award value and date, contract period, CPV codes, category, procurement method) and explains that q spans all text fields and filters AND together. It leaves date-format and page/per_page interaction unexplained, so not a full 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: award notices from the Contracts Finder OCDS feed flattened to one row per award and supplier. It also implicitly distinguishes itself from the sibling query_uk_tenders by framing the resource as awards ('who won which contract, for how much') rather than tenders.

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 concrete operating context: a rolling two-week window refreshed daily, filters combining with AND, q searching all text fields, and credit/preview cost limits. It stops short of explicitly naming when to prefer a sibling such as query_uk_tenders, so it is clear but not fully routing.

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 readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: daily refresh cadence, dropped fields (operator comments and rating artwork), the preview cap of 5 rows and 20 calls/day without a key, and 1-credit cost with a key. This is exactly the behavioral detail an agent needs.

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 what the tool returns before touching operational details (filters, cost, limits). Dense but each clause earns its place; only the field enumeration is slightly long-winded.

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, so listing returned fields and the FHRSID key is genuinely useful, and refresh/cost/limit behavior is covered. However, for a 20-parameter tool with zero schema descriptions, the near-total absence of per-filter semantics leaves a real gap an agent must guess at.

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?

With 20 parameters at 0% schema description coverage, the description carries the full semantic burden but explains only two things: q searches all text fields and filters combine with AND. It never clarifies the many filters (scheme_type, outward_code, rating_value, the min/max score pairs, new_rating_pending, pagination bounds), leaving most parameters opaque.

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: querying the official FSA Food Hygiene Rating Scheme file for England, Wales, Northern Ireland and Scotland FHIS. The enumerated returned fields and the FHRSID key make the scope unmistakable, and it is clearly distinguishable from the other query_uk_* siblings.

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 that filters AND together and that q searches all text fields, plus the geographic coverage (Scotland uses FHIS), which helps an agent decide applicability. It does not name when to prefer this over other sibling datasets or state prerequisites (e.g. API key requirement per plan), so it stops short of explicit when/when-not 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?

Goes well past the read-only/idempotent annotations: it discloses the daily-register provenance, the exclusion of personal licences held by individuals, the cost (1 credit/call), and the unauthenticated rate limit (5-row preview, 20 calls/day). That is exactly the operational context an agent needs before invoking.

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 resource and scope, then record granularity, then provenance and cost. Dense but no filler; the two long sentences are information-heavy 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?

With no output schema, the description usefully enumerates the return columns and the per-record_type keying, and it documents access limits. The remaining gap is parameter semantics, which is significant given 21 undocumented fields, but the coverage model is otherwise solid.

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 must carry the load. It only explains q (searches all text fields) and that filters AND together; the meaning of city, postcode, outward_code, local_authority, licence_type, status, activities and the four date-bound params is left entirely 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?

States a specific resource (Gambling Commission operating licences for Great Britain) and enumerates the covered licence categories, activities, dates and trading names. An agent can immediately distinguish this from sibling query_uk_* datasets such as query_uk_companies or query_uk_charities.

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?

"Filters combine with AND; q searches all text fields" tells the agent how to drive the query, and the credit/preview note signals the cost model of calling it. It stops short of explicit when-to-use-vs-alternative routing, though the dataset boundary makes that largely self-evident.

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 cover readOnly/idempotent/non-destructive, and the description adds material context beyond them: the Blind Mode ingestion policy (person fields and notice text never ingested), a per-call credit cost, and the unauthenticated preview cap of 5 rows / 20 calls per day. These are exactly the operational facts an agent needs and 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 what the tool is, then compressed into scoping, privacy, filter and cost sentences. Slightly dense with three ideas packed into the closing sentence, but no filler or 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?

No output schema exists, and the description partially compensates by noting 'company-level facts only' plus cost and access limits. It still leaves the return shape and the meaning of most filter parameters unstated, which is the main remaining gap for a 0-required, 8-param 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% across 8 parameters, so the description carries the full burden and does not meet it. It explains only q (searches all text fields) and the AND-combination rule; company, notice_code, notice_type, page, per_page and the published_at bounds are left undocumented beyond their names.

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 (query) and resource (corporate insolvency notices from The Gazette) and enumerates the covered notice categories (winding-up, administrator/receiver/liquidator appointments, moratoria, creditor notices). The dataset is unmistakably distinct from every sibling query_uk_* tool, so an agent can route without opening the schema.

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?

It gives operational guidance: filters combine with AND and q searches all text fields, plus cost and preview limits. It never names an alternative or a when-not-to-use condition, but the sibling set is disjoint by dataset, so there is little risk of misrouting.

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 by disclosing Blind Mode (no applicant personal data), the credit/preview regime, and critically an origin notice that the upstream dataset was emptied and this tool currently returns no records. That last disclosure is exactly the kind of behavior an agent needs and could not learn 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?

Purpose is front-loaded and the dense semicolon-separated clauses are mostly load-bearing. The origin notice partially repeats itself ('Paused since then on every surface' details), which is slightly verbose but justified given its importance.

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?

Covers privacy, cost, rate limits and the paused-dataset reality well, which is strong for a tool with no output schema. However, six of seven parameters remain semantically undocumented, so an agent still cannot construct a meaningful filtered query.

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?

With 0% schema description coverage across 7 parameters, the description must carry the full burden, yet it only explains q (searches all text fields) and the AND-combination rule. authority (a number), reference, decision_date_after/before, page and per_page are left entirely undefined.

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 ('Planning applications') and its authoritative source ('official planning.data.gov.uk feed, normalized to one schema'), which cleanly distinguishes it from the many sibling query_* tools. An agent can identify exactly what data domain this returns.

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?

Provides useful operational context (filters combine with AND, q searches all text fields, credit cost, preview limit) but never states when to choose this over alternatives or conditions for use. Usage is implied rather than guided.

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 annotations already covering safety (readOnly, idempotent, non-destructive, closed-world), the description goes well beyond them: it discloses that DOB, identity documents, and contact details are dropped at ingest, states the cost (1 credit/call with a key) and the unauthenticated cap (5-row preview, 20 calls/day). These are exactly the operational constraints an agent needs before invoking.

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 sentences, front-loaded with what the corpus contains, then data-handling caveat, then cost/limit. Dense without waste, though the em-dash clause 'with regimes, aliases, and dates' is slightly unpacked relative to its value.

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 13-parameter, no-output-schema tool, the description compensates well on the result side: it describes record contents (regimes, aliases, dates) and what is redacted (PII), plus cost and preview limits. The main gap is filter semantics for the many query parameters, which are neither in the schema nor the description.

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 13 parameters, so the description carries the full semantic burden but only clarifies 'q' (searches all text fields) and the AND-combination rule. Key filters — name (exact vs. partial match), regime, countries, designation_type, designation_source, unique_id, and the four date bounds — are left undocumented in both schema and description.

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 and scope: 'Every designation on the official UK Sanctions List (FCDO) — individuals, entities, and ships.' The dataset ('UK Sanctions List') is distinct enough from the query_uk_* siblings and query_eu_ted that an agent can tell it apart, but the verb is implicit (retrieval/search) rather than stated, and no sibling is named to confirm the boundary.

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?

'Normalized for supplier due diligence' implies a use case, and 'Filters combine with AND; q searches all text fields' gives operational guidance for combining filters. However, there is no explicit when-to-use/when-not guidance and no routing to or away from alternative tools (e.g., query_eu_ted, query_sam_exclusions), so usage must be inferred.

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 (which only cover read-only/idempotent/open-world) by disclosing ingest exclusions (head-teacher names and phone numbers dropped, governors extract never ingested), source freshness cadence (daily GIAS, monthly Ofsted MI), and rate-limit/preview behavior. These are precisely the traits an agent cannot infer 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 what the tool returns before covering sources and cost; four sentences with little waste. The field enumeration is long but justified given 22 queryable columns, so it earns its space without being 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?

With no output schema, the description usefully enumerates returned fields and the Ofsted join, and covers cost and preview limits. It omits pagination semantics for page/per_page and the valid values for categorical filters, which slightly under-serves a 22-parameter 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?

With 22 parameters at 0% schema description coverage, the description must carry the load, but it only clarifies two behaviors (q searches all text fields, AND-combined filters). Many parameters (urn, name, phase, region, status, ofsted_rating, pupils_min/max, date bounds) are self-naming, so 3 is fair, but no enum values or range/format semantics are supplied for fields like phase, status, or website_present.

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 DfE GIAS register of schools/colleges/nurseries) and enumerates the field families it returns, plus the Ofsted join by URN. An agent can distinguish it from sibling query_uk_* tools purely from the description, since it names its two data sources 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?

Explains how filters behave ('Filters combine with AND; q searches all text fields') and the cost/access model (1 credit with API key, otherwise a 5-row preview at 20 calls/day), which is real invocation guidance. It stops short of explicitly naming when to prefer or avoid this tool versus alternatives, but the sibling set is domain-disjoint so the gap is small.

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 cover read-only/idempotent/openWorld, and the description goes well beyond them: refresh cadence ('refreshed on every republication, most working days'), cost model (1 credit per call), and an unauthenticated preview cap (5 rows, 20 calls/day). These are exactly the operational facts an agent needs before invoking.

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?

One dense paragraph, but front-loaded with the dataset and its scope before cost and auth details. Every clause carries information; only the trailing pricing/preview sentence sits slightly apart from the core purpose.

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, the description usefully enumerates returned fields, which is the right compensation. The remaining gap is pagination/value-format guidance for a 9-parameter tool, which is left entirely to an undocumented 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?

Schema description coverage is 0% across 9 parameters, so the schema carries no meaning on its own. The description partially compensates by naming filterable fields (organisation, town, county, sponsor_type, route, rating) and the AND/q semantics, but says nothing about page/per_page behavior or accepted values for route, rating, and sponsor_type.

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 the specific resource (Home Office register of licensed sponsors for Worker and Temporary Worker routes) and enumerates the returned fields, so an agent can distinguish it from the many sibling query_uk_* datasets without opening the schema.

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 to use it (filters combine with AND, q searches all text fields) and gives context on data scope ('organisation-level data only', one row per organisation and route), but does not state when to prefer it over the other query_uk_* tools or any 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed world), and the description adds substantial context on top: Blind Mode with no contact or personal data, per-call credit cost with an API key, and the unauthenticated preview cap of 5 rows / 20 calls per day. Rate limits, auth requirements and data-privacy behavior are exactly the kind of traits annotations cannot express.

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, no filler, and the most important facts (source, schema shape, query semantics, cost) are front-loaded before the pricing caveat. Nothing here is redundant with the name or title.

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 11 undocumented parameters, an agent still lacks the return shape (beyond the hint 'flattened to one queryable schema') and the semantics of most filters and date fields. The pricing/preview caveats are valuable, but the parameter coverage gap keeps this from being fully sufficient 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 0% across 11 parameters, so the description carries the full burden and mostly does not meet it. It clarifies only q ('searches all text fields') and the AND-combination rule; buyer, status, cpv_codes, value_amount_min/max, procurement_method, page, per_page and the two date bounds are left entirely undocumented, including format expectations such as CPV code lists or date ranges.

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 and provenance: 'Public procurement notices from the official Find a Tender OCDS feed, flattened to one queryable schema.' That is far more than a restatement of the name and lets an agent distinguish it from generic query tools. However, it never explicitly contrasts itself with the very close sibling query_eu_ted (EU vs UK scope), so the differentiation is implied by the name 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?

'Filters combine with AND; q searches all text fields' gives real usage mechanics for composing a query, which is more than nothing. But there is no guidance on when to choose this tool over the adjacent query_eu_ted or query_uk_contract_awards, nor any exclusions or prerequisites beyond the credit/API-key note. Usage is implied through mechanics rather than routed.

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 readOnly/idempotent/non-destructive annotations: privacy handling (applicant names only for organisations, addresses reduced to country, mark images never stored), the 52-issue rolling window, and the cost model (1 credit/call with a key, otherwise a 5-row preview at 20 calls/day). These are exactly the operational traits an agent needs and none are in the schema or annotations.

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 paragraph that front-loads what the tool is, then coverage, privacy, and cost. Every sentence carries information, though the run-on field enumeration makes it slightly harder to scan than it could be.

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 23-param, no-output-schema query tool, it covers provenance, coverage window, privacy caveats, filter logic, and cost/pagination limits, and it lists the returned fields in lieu of an output schema. The missing piece is per-filter syntax for the many unlisted parameters.

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 23 params, so the description must compensate. It explains q ('searches all text fields') and that filters combine with AND, and its field list implicitly maps to many params (mark_text, classes, applicant_country, filing/publication dates, journal_number). But syntax and scope for the remaining filters (origin, section, applicant_type, class_count_min/max) remain undocumented, so compensation is only partial.

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: 'Every UK trade mark application and international registration designating the UK accepted and published in the Intellectual Property Office's weekly Trade Marks Journal,' then enumerates the fields returned. It is immediately distinguishable from siblings like query_uk_companies or query_uk_insolvency by its domain and source publication.

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 clear operational context: rolling 52 weekly issues, a change feed for each week's new publications, AND-combining filters, and the q full-text behavior. It hints at the get_changes alternative but does not explicitly name it or state when to prefer one over the other, so it falls 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?

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=false, openWorldHint=false) by disclosing the side effect (an email is sent to the user), the human approval/code-match step, the required 15s polling of claim_api_key, and the cost terms (250 free credits/month, no card, existing plan carries over). This is exactly the behavioral context an agent needs before invoking.

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 core action is front-loaded and nearly every clause carries needed information (side effect, next step, cost). It is a dense run-on chain rather than cleanly segmented sentences, which slightly hurts scannability, but little 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?

With no output schema, the description compensates by explaining the returned code and the request_id/claim_secret needed for claim_api_key, plus cost and auth context. It does not cover error/failure handling, so it is strong but not fully complete.

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 both email and client_name are already documented with format details and intent. The description only restates 'give the user's email address' and does not add meaning to client_name, so the baseline 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?

States a specific verb and resource ('Start sign-up', 'request_api_key') and explains the concrete outcome: gankdat emails the user a one-click approval link. It is clearly distinguishable from the query siblings and explicitly links to claim_api_key as the follow-up step.

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?

Tells the agent exactly when to use it (start sign-up from inside the agent), what to do afterward (show the code, then poll claim_api_key every 15s), and the precondition that it is free and needs no existing key. The workflow routing to the sibling tool is explicit.

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