UK Rules & Rates

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds genuinely new context: it is a paid endpoint ($0.005/call via x402 or an API key) and it computes from "verified UK Rules data," which speaks to data provenance. It does not disclose rate limits or the response shape, keeping it below a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded in the first sentence and the text is short. Minor redundancy: "Paid." is emitted as a standalone fragment and then repeated as "Paid: $0.005 USD per call," which wastes a line.

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 calculation tool with no output schema, the description should say what comes back (per-employee NI amounts, totals, employment-allowance handling). It covers payment and data provenance well but leaves the return values and result semantics unspecified.

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 date format, salary bounds, the 1-200 employee limit and the employment-allowance flag are all already documented in the schema. The description only restates salaries and date at a high level, adding no format or semantic detail beyond the structured fields, so 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?

States a specific verb (calculates) and resource (employer Class 1 National Insurance) plus scope (one or more annual salaries, on a date). It is clearly distinguishable from the sibling tools, which are rule/rate/company lookup utilities rather than a calculator.

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?

"Use this instead of doing the maths yourself" gives a clear directive for when to reach for the tool, and the cost note frames the trade-off. It stops short of naming exclusions or alternatives (e.g. when a generic get_rate lookup would suffice), so it is strong context without full routing guidance.

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

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

Annotations only declare readOnlyHint/openWorldHint, but the description adds substantial operational context: billing ($0.02 via x402 or API key), that it consumes 2 calls against a quota, the exact field set returned including per-item source_url, and the caveat that vat_number is accepted but unchecked. This is well beyond what the annotations convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core purpose and keeps everything in a compact block, but the dense comma-separated field enumeration makes it a single heavy run-on. Every element is load-bearing given there is no output schema, so little could be cut.

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 still discloses the return contents, the source_url tracing, the cost/quota implications, and the scope exclusions. An agent has everything needed to decide and call it 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 description coverage is 100% and the schema already defines company_number format examples and flags vat_number as unvalidated, so the description largely restates structured data. Baseline 3 applies when the schema carries the parameter burden.

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 ('Sourced check of a UK company from Companies House') and then enumerates exactly what is checked: status, incorporation date, registered office, SIC codes, filing health, insolvency/charges flags, officers and PSCs. An agent can distinguish this immediately from search_uk_company (lookup) or get_rate-style 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?

Gives explicit exclusions ('Not a credit check, sanctions or PEP screening') and warns that the VAT portion is not yet functional, so the agent knows when this tool is the wrong choice. It does not name a sibling alternative directly, though the company_number schema points to search_uk_company for discovery.

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 this is a read-only, closed-world lookup. The description adds genuinely useful context beyond them: the useful output fields (value, unit, effective dates, source), the pricing model ($0.005/call via x402), and the alternative API-key auth path. It stops short of rate limits or fallback behavior detail.

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: what it does, what it returns, and the cost/auth terms. Zero filler and the core purpose is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema present, the description compensates by naming the returned fields (value, unit, effective dates, source) and covering cost and authentication. An agent has everything needed to invoke it 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 description coverage is 100%, so the baseline is 3. The description only restates the date default (today, Europe/London) and the UK scope, adding little beyond what the schema already documents for key, date, and jurisdiction.

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?

Specific verb+resource with the key qualifying detail: the rate/threshold 'in force for a key on a date'. The temporal phrasing ('in force for a date') implicitly separates it from get_rate_history, but no sibling is named explicitly, so it stays just 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?

Usage is implied by the description (fetch the currently effective rate for a given rule key), but there is no explicit when-to-use / when-not-to-use guidance and no routing to siblings like get_rate_history or search_rules. Adequate but with clear gaps.

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=true and openWorldHint=false, and the description usefully adds a real behavioral trait: a per-call cost of $0.005 USD with two payment paths (x402 or API key). It does not disclose result size, pagination, or completeness behavior for what could be a long version list.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the capability and ordering before the payment note. No filler, though the pricing sentence, while operationally relevant, is not about how to invoke the tool correctly.

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 states what is returned (all versions, ordered by applies_from) and the cost model, which is adequate for a simple two-parameter read tool with no output schema. The remaining gap is that 'key' is never characterized, leaving a required parameter semantically thin.

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%: 'jurisdiction' is documented in the schema ('Omit for all jurisdictions') while 'key' has no schema description and the tool description never explains what key identifies (presumably a rule identifier) or its format constraints. The description fails to compensate for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource ('Get every version of a rule') plus the ordering contract ('ordered by applies_from'), which clearly distinguishes a history lookup from the sibling get_rate. It never names that sibling explicitly, so the differentiation is implicit rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: 'every version' suggests this is for historical/versioned lookups while get_rate would be for a current value, but no when-to-use, when-not, or named alternative is provided. An agent must infer the routing decision from the word 'history'.

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 readOnlyHint/openWorldHint annotations, it discloses how fixed-date entries resolve to a next due date, the Europe/London default, the to_date filtering, and that period-dependent regimes (VAT, Corporation Tax, Companies House) return next_due null with a recurrence_rule. It also surfaces the x402 pricing/API-key auth model, which is real operational context. Return shape is only partially described, keeping it short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The core listing behavior is front-loaded and the two sentences carry dense, non-redundant information. The second sentence is long and packs pricing alongside result semantics, which slightly blurs the structure.

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 must explain the returned fields, and it does so concretely (next_due, recurrence_rule, the null case). Combined with annotations covering the read-only profile and 100% schema coverage on both parameters, an agent has everything needed to call it 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 already 100%, so the schema baseline applies, but the description adds genuine meaning: from_date is not just a boundary but the anchor used to compute the next due date, and to_date truncates the result set. That is semantics the schema's terse 'YYYY-MM-DD' pattern does not convey.

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 ('List UK tax/payroll deadlines') and elaborates on what the listing contains, which clearly separates it from rate/company/rule siblings. It never names an alternative tool, so differentiation is by domain rather than explicit contrast.

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 date-range mechanics: the caller infers this is for enumerating deadlines inside a window. There is no explicit statement of when to prefer this over check_uk_business or search_rules, and no exclusions or prerequisites are given.

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

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

Annotations declare readOnlyHint=true and openWorldHint=false, so the safety profile is already covered. The description does add that each topic is returned with a rule count, which is useful return-shape context absent from annotations and the (nonexistent) output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with the verb first, examples inline, and no filler. Every element 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 zero-parameter, read-only listing tool with no output schema, the description conveys what is returned (topic names plus rule counts), which is sufficient to call it correctly. Minor gaps: no mention of ordering or how topics relate to search_rules.

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 of 4 applies; there is nothing for the description to clarify beyond what the empty schema already conveys.

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 (List) and resource (rule topics), and gives concrete examples of topic identifiers (income_tax, vat). It doesn't explicitly contrast with siblings like search_rules, but the resource is distinct enough that an agent can distinguish them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No statement of when to use this versus search_rules or get_rate; usage is only implied by the notion of browsing topics. No prerequisites, ordering, or exclusions are given.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral context — that this call is free while get_rate is paid, and that it returns keys rather than values — which steers cost-aware tool selection.

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 clipped sentences, zero waste, with the most decision-relevant fact ('Free') front-loaded and the routing hint last. Every clause 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 one-parameter, no-output-schema lookup tool, the description covers purpose, cost, and return nature (keys). It could be marginally richer about what happens on no match, but nothing essential to a correct call is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single 'query' parameter is documented with an example ('vat threshold'), so the description carries no additional parameter burden. Baseline 3 is appropriate since the schema does the work.

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 ('Finds rule keys'), and explicitly contrasts itself with the sibling get_rate. An agent can immediately tell this is the key-discovery tool rather than the value-lookup 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?

Names the alternative (get_rate) and the exact condition that selects it ('to get the value in force on a date'), which by contrast defines when to use this tool: when the key itself is unknown. Nothing 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 declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds genuinely useful behavior not in the structured fields: the result cap of 10 matches and the exact fields returned (name, company number, status, incorporation date), which matters because there is no output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences with zero filler, front-loading the action and scope before the downstream routing hint. Every sentence carries distinct information (purpose, cost, return shape).

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 search with no output schema, the description supplies the return cap and field list an agent needs to consume the result, plus the relationship to the next tool. Nothing required to call or interpret it 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?

With 100% schema description coverage on a single parameter, the schema already documents the query field and its example. The description adds no format, matching, or disambiguation guidance beyond what the schema provides, so 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?

Specific verb (Search) plus resource (Companies House for UK companies by name) with an explicit scope. It also distinguishes itself from the sibling check_uk_business by naming that tool as the downstream consumer, 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?

Clearly states the context of use: run this first to obtain a company_number for check_uk_business, and notes the call is free. It does not state any when-not conditions (e.g. what to do if you already have a company number), so it falls short of a full 5.

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