0s and 1s CIS calculators

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

Annotations already mark it readOnly/idempotent/non-destructive, and the description goes well beyond them with real behavioral content: VAT is never taxed under CIS, materials come off before the rate applies, the deduction is rounded down to the penny, and the return contains each step in pence and pounds. That is exactly what an agent needs to trust and interpret a calculation tool.

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

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

Three tightly packed sentences, front-loaded with the calculation and direction, then the rules, then the return shape and exclusions. No filler, and the semicolon clauses each carry a distinct rule rather than 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?

There is no output schema, yet the description covers the return shape ('each step of the working, money in pence and pounds'), the money-unit convention, and the domain rules. Combined with annotations covering safety, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so each parameter (gross, vat, materials, rate enum) is already documented in the schema. The description restates the inputs and their relationships but adds no new per-parameter syntax or format detail beyond what the schema carries; 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+resource and pins down the direction explicitly: 'Works out the CIS deduction on a payment to a subcontractor, from the gross bill to the net payment.' The gross-to-net direction is exactly the axis that distinguishes it from the cis_gross_up sibling, so an agent can route 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?

Gives explicit scope exclusions — 'Does not cover retentions, or decide which rate applies (verify the subcontractor with HMRC for that)' — which routes rate-determination work toward cis_needs_verification. There is no positive 'use this when...' trigger, but the direction statement plus exclusions give the agent enough to select correctly.

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, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine value beyond that: it discloses the return content (which route applies, how far short of the threshold) and the legal basis for the computation, which shapes how an agent interprets the result.

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 purpose before the numeric rules, then the return shape, then the scope limitation. Each sentence earns its place, though the full statutory citation (Finance Act 2004 Schedule 11, SI 2005/2045 reg 28) is heavier than needed for selection.

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 carry return-value burden, and it does — stating it returns the required figure per route, which route applies, and the shortfall. Numeric rules and the close-company treatment fill in the domain logic the agent needs to reason about inputs. Only minor gaps remain, e.g. no rounding/currency handling notes.

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 field meanings (partners, directors, shareholders, net_turnover, business_type, close_company) are already fully documented. The description contributes interpretive context (shareholders count alongside directors in a close company; thresholds applied per person) but no syntax or format detail beyond the schema, so the baseline 3 is warranted.

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 (checks) and resource (CIS turnover test for gross payment status), names the governing legislation, and precisely defines the computation (£30,000 sole trader; lower of £30,000 per partner/person and £100,000 otherwise). It is clearly distinguishable from siblings such as cis_deduction, cis_gross_up and cis_late_penalties, and it declares its output shape ('the figure needed by each route, which one applies, and how far short').

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 scopes the tool with a when-not clause: 'Covers the turnover test only, not the business test or the compliance test.' That tells the agent when this tool is insufficient (partial qualification assessment). It does not name sibling tools or state when-turnover-test-is-relevant preconditions, 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?

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely non-obvious behavior: the rounding tie-break that returns the larger gross so CIS is never under-deducted, the return shape (forward working, pence and pounds), and the VAT-exclusion caveat. That is meaningful context beyond the structured fields, though it does not discuss limits or errors.

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

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

Four sentences, all earning their place, with the core purpose front-loaded and the rounding rule and VAT caveat following. Slightly dense but no filler.

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

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

With no output schema, the description steps in to explain what comes back (forward working, pence and pounds) and flags the rounding determinism and VAT exclusion. For a 3-param read-only calculator that is essentially complete; only explicit routing to the sibling tool 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%, so net, materials and rate are already fully documented in the schema, including the 0/20/30 enum meanings. The description adds the framing that net is post-CIS and VAT-exclusive, but no new syntactic or edge-case detail beyond the schema baseline.

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 precise verb+resource: finds the gross amount (excluding VAT) from a given net after the CIS deduction. The title's 'net to gross' and the explicit 'for a subcontractor quoted a take-home figure' clearly distinguish it from the forward-direction sibling cis_deduction.

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 context (subcontractor quoted a take-home figure, so you need to work backwards), which is exactly the situation that selects this tool over cis_deduction. However, it never explicitly names cis_deduction as the alternative for the forward direction, so the routing 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 already declare this a safe, read-only, idempotent, closed-world calculation, so the safety profile is covered. The description adds genuine behavioral context beyond them: the exact penalty schedule applied, and that the result is per-penalty with a charged/avoided/still-to-come status. With no output schema, this return-shape disclosure is the main thing carrying the burden.

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?

Dense but front-loaded: purpose, then the exact computation, then inputs, then return shape, then exclusions. The penalty-formula sentence is long, but every clause carries information the agent cannot get elsewhere. No filler sentences.

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?

A six-parameter calculation tool with no output schema needs to explain both its inputs' roles and its output shape, and this description does both, plus states the excluded regimes. An agent has everything required to call it correctly and interpret the result.

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 every parameter (including the as_at/filed_on nil-filing distinction and filed_before's effect on the £300 minimum) is already documented in the schema. The description's sentence 'takes the tax year and month, the filing date or none, today's date, the deductions and whether a return had been filed before' mostly restates the schema. 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+resource ('works out the late filing penalties on one monthly CIS return') and names the governing legislation (Finance Act 2009 Schedule 55), then spells out the actual rate structure. Nothing else in the sibling set computes penalties, so the distinction from cis_deduction, cis_gross_up and cis_tax_month is unambiguous.

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 scope boundaries: 'Does not cover deliberate withholding, interest on late payment, or appeals' tells the agent when this tool is the wrong choice. It does not, however, point to any alternative tool for those cases, so routing for out-of-scope questions 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 mark this as a read-only, idempotent, closed-world, non-destructive operation, so the safety bar is low. The description adds genuine context beyond them: it performs no HMRC lookup and verifies nobody, and it explicitly scopes out group companies and business transfers. It does not, however, describe what the returned answer looks like.

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 tight sentences: the verdict and its legal basis come first, the qualifying rule second, and the negative boundaries last. Every clause carries information; there is no filler or repetition of the 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?

The decision rule, its legal source, the required inputs and the out-of-scope scenarios are all covered, which is ample for a 3-parameter closed-world predicate. The one gap is the absence of an output schema combined with no statement of what form the answer takes (boolean, plus reason, etc.).

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%, with formats (YYYY-MM-DD) and the array/comma-separated convention already documented, so the baseline is 3. The description restates the three inputs and reinforces that they are caller-supplied (supporting openWorldHint=false), but adds no syntax or edge-case semantics the schema lacks.

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

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

States a specific verb and resource ('says whether a contractor must verify a subcontractor with HMRC before paying them') and anchors it to a legal rule (SI 2005/2045 reg 6). It is clearly distinguishable from the sibling tools, which deal with deductions, turnover tests, grossing up, penalties, nil returns and tax months rather than a verification obligation.

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 the positive condition for 'not needed' (subcontractor on one of this contractor's CIS returns, or verified by this contractor, in the payment tax year or the two before) and explicit exclusions ('does not cover group companies or business transfers'). It does not name a sibling alternative for the excluded cases, so it stops short of full when/when-not 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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. Beyond that the description supplies the decision rule and the 14-day notice exception, plus 'Does not file anything' to reinforce read-only behavior. It stops short of describing error cases or how the date is derived.

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 answer the tool gives, then the rule, then the return shape and the non-action caveat. Dense but every clause carries meaning; the inline statutory citations are long but justified for a compliance determination.

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 stating what comes back ('whether a nil return is due, why, and the date it is due'). Inputs, the governing rule, the exception, the return contents, and the fact that nothing is filed are all covered, leaving nothing an agent needs 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 description coverage is 100%, so every parameter is already documented, including the mainstream_contractor vs deemed contractor distinction and the date format. The description only summarizes ('Takes the tax year and month and yes or no answers') and adds no format or edge-case detail beyond the schema, 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 precise verb and resource: 'Says whether a contractor must file a CIS nil return for a tax month.' It also cites the exact statutory basis (SI 2005/2045 reg 4(9A)/(9B), SI 2026/289), which no sibling covers -- the other tools handle deductions, gross payment tests, or penalties, so the boundary is unambiguous.

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

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

The description gives the substantive trigger condition (mainstream contractor, previously paid subcontractors, no payments this month, no advance notice to HMRC at least 14 days before month start), which tells the agent when the tool is relevant. It also closes the action-vs-check boundary with 'Does not file anything.' It never names a sibling alternative, so it falls short of the 5 bar.

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 read-only/idempotent safety profile, so the bar is lower, yet the description adds substantial domain behavior: the 6th-to-5th month rule, the 19th non-electronic due date, the 22nd electronic date moving back to the prior banking day on weekends or England-and-Wales bank holidays, and the limitation that bank holidays are only known up to the bank_holidays_known_until date. That is exactly the kind of edge-case context an agent cannot infer.

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

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

A single dense sentence, front-loaded with 'For a date, gives the CIS tax month...', then building outward through each derived date. Despite its length, every clause carries distinct information (month boundary, year, two due dates, holiday-shift rule, known-holiday limit) with no 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?

With no output schema, the description carries the burden of explaining return values and does so fully — four named outputs plus the bank-holiday shift caveat. An agent has everything needed to call the tool and interpret the result.

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 is a single parameter at 100% schema description coverage, so the schema already documents the 'date' field including its YYYY-MM-DD format and example values. The description restates that a date is supplied without adding format or constraint detail beyond the schema, which is the expected baseline 3.

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

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

Names a specific verb and resource ('for a date, gives the CIS tax month it falls in, the tax year, the CIS300 due date, the electronic payment date') and enumerates the exact outputs. The scope is unmistakable and clearly differs from siblings like cis_late_penalties or cis_deduction.

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 makes the use case evident — supply a date (payment date or today) to obtain CIS period and deadline information — which is clear context for a pure calculation tool. It does not, however, explicitly state when to prefer this over sibling tools such as cis_late_penalties, so it falls short of full 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.