GetAccountED — South African Tax Tools

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety bar is low; the description still adds useful trust context by noting the ID number is 'not stored' and by pinning down defaults (tables method, monthly period, today's pay date, monthly-equivalent conversion). It does not state determinism or rate-table vintage caveats explicitly beyond 'the right tax year'.

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

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

Two sentences, front-loaded with the outputs and scope, then a compact enumeration of the statutory features handled. The second sentence is a dense list but every item maps to real parameters, so nothing is padding; a slightly tighter grouping of the tax-credit and allowance features would make it easier to scan.

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, read-only calculation tool with no output schema, the description names the computed outputs (PAYE, UIF employee/employer, SDL, net pay) and the scope constraints, which is close to sufficient. The remaining gap is that the exact response fields and any rounding/table-version disclosure are left implicit.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above baseline by tying parameters to substantive statutory mechanics the schema only gestures at — the s11F cap, the 80%/20% travel allowance split, the annual-payment method for bonuses, and age rebates and medical credits. It does not resolve ambiguities such as how salary plus overtime plus bonus interact when period is weekly.

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-resource-scope: it computes PAYE, UIF (employee and employer, with ceiling), SDL and net pay for exactly one employee and one pay period. That scope line alone separates it from siblings like sa_tax_rates (rate lookup) and sa_vat_calculate (indirect tax) without needing their schemas.

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 single-employee/single-period scope implies when to use it, and the mention of 'the right tax year' hints at the pay_date/tax_year choice, but no explicit when-not or alternative is named, and no sibling is referenced for related tasks such as validating an ID number or looking up rates.

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

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

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral detail beyond that: EMP201 falls on the 7th but moves earlier for a weekend or public holiday, VAT201 eFiling lands on the last business day of the month following the period, and the calendar is computed against South African public holidays. It does not describe the shape or ordering of the returned events.

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 front-loaded sentence establishes the resource and scope before enumerating obligations; nothing is padding. The long parenthetical list of return types makes it dense and slightly run-on, but each clause carries substantive information about a distinct tax obligation.

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 nine-parameter tool with all-optional inputs and sensible defaults documented in the schema, the description covers scope, the tax obligations produced, and the holiday-shifting logic. The main remaining gap is that there is no output schema and the description never says what a result entry looks like (date plus obligation label, ordering, inclusion of descriptions), which an agent would need when composing an answer.

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, but the description adds real meaning by tying parameters to outputs: vat_category A–E drives VAT201 frequency, entity_type drives ITR14/CIPC returns, incorporation_date feeds the CIPC annual return, and year_end_month anchors the tax year. This tells an agent which optional parameters actually change the result rather than merely restating the enum labels.

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 opens with a specific verb-and-resource statement: 'SARS (and CIPC) due dates in a date range', then names the exact obligations covered (EMP201, VAT201 categories A–E, IRP6, EMP501, ITR14, CIPC annual returns). That enumerations makes it instantly distinguishable from the sibling calculators (sa_paye_calculate, sa_vat_calculate, sa_tax_rates) without opening their schemas.

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 phrase 'due dates in a date range' and by the parameters that gate which obligations apply (payroll, provisional_taxpayer, vat_category, entity_type), but there is no explicit when-to-use/when-not-to-use statement or a named alternative. An agent can infer the fit, but nothing steers it away from this tool when a rate or calculation is actually wanted.

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, openWorldHint=false, and destructiveHint=false. The description adds useful behavioral context by stating that data is available for current and prior tax years and that it comes from GetAccountED payroll tables, though it does not describe the response shape.

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

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

The description is a single front-loaded sentence that efficiently lists the data categories. It is dense but largely earns its length by naming the specific tax components covered.

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

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

For a simple two-parameter, read-only reference tool with a fully described schema and no output schema, the description provides enough information to know what data is returned. The main gap is the lack of explicit routing guidance relative to sibling calculator tools.

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 tax_year and compare_previous are already well documented. The description reinforces the current/prior-year scope but does not add format, default, or edge-case semantics 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 clearly specifies the resource: South African tax rates and thresholds, listing brackets, rebates, UIF, SDL, VAT, and related payroll tables. It is more specific than the title alone, but it does not explicitly distinguish itself from sibling calculators such as sa_paye_calculate or sa_vat_calculate.

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: an agent can infer this tool retrieves reference rates rather than calculating tax. However, there is no explicit guidance on when to use this versus sa_paye_calculate, sa_vat_calculate, or sa_tax_calendar, and no stated 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 declare readOnlyHint, idempotentHint, closed-world and non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: it lists the actual checks performed (Luhn check digit, date of birth, gender, citizenship) and states the key limitation that these are offline checks that do not confirm registration. It stops short of describing what happens on an invalid input or the shape of 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?

Two sentences, front-loaded with the core operation and the enumerated coverage, then a closing limitation clause. No filler, no repetition of the title or annotations.

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 two-parameter, read-only, closed-world tool with no output schema; the description covers scope, validation rules per type, and the offline caveat. Only a brief note on the return value (valid/invalid plus derived attributes) would make it fully self-contained.

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

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

Schema coverage is 100%, so baseline is 3. The description goes further by clarifying what each enum value validates (VAT is 10 digits starting with 4; ID covers Luhn, DOB, gender, citizenship), which gives the agent real meaning for the 'type' parameter choices rather than just restating the enum.

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

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

The description names a specific verb+resource ('Format and check-digit checks for South African numbers') and enumerates exactly which number families are covered (ID, income tax, VAT, PAYE/SDL/UIF, CIPC). This cleanly separates it from the sibling tools, which are all calculators rather than validators.

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 enumerated number types and the 'default auto-detect' schema note, so an agent can infer this is the pre-check tool. However, there is no explicit when-to-use routing (e.g. 'run this before sa_vat_calculate or sa_vat_classify') and no stated when-not-to-use conditions beyond the offline limitation.

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 read-only, idempotent, non-destructive and closed-world, so the safety profile needs no restating. The description still adds real value by disclosing historical rate selection via date (15% since 1 April 2018) and the shape of the result — per-line plus total figures. It stops short of stating rounding rules or what happens for zero/exempt lines.

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 operation and rate context are front-loaded in the first sentence with no wasted clauses. The trailing fragment 'One amount or a list of lines, with per-line and total figures' carries useful information but reads as an unanchored afterthought rather than a complete 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?

For a parameterless-required, read-only calculator with full schema coverage and no output schema, the definition is nearly sufficient — it even summarises the return shape as per-line plus total figures. The remaining gap is edge-case behavior (zero-rated/exempt lines, rounding, mixing amount with lines), which an agent would have to 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 coverage is 100%, so the schema already documents all four parameters including the 'inclusive' default and 'vat' enum meanings; that sets the baseline at 3. The description adds a little by framing 'amount' and 'lines' as alternatives ('One amount or a list of lines') and by tying 'date' to the rate history, but it does not explain 'quantity' or how per-line 'inclusive' interacts with the top-level flag.

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 concrete verb+resource pair ('Split a VAT-inclusive amount into VAT and the exclusive price, or add VAT to an exclusive amount') with the exact rate and effective date. This is unmistakably a calculator, which separates it from sa_vat_classify, sa_vat_rates, and the PAYE sibling 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?

Usage is implied by the operation described, and 'at the rate in force on the date' hints that historical dates select older rates. However, it never says when to prefer sa_vat_classify for treatment questions or sa_vat_rates for raw rate lookup, and gives no exclusions or prerequisites.

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 carry the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's added value is what it discloses beyond that: answers come from a curated rules table with a cited Act section per rule, supplementary material is pulled from the GetLawED library, and it states plainly when no rule matches. The one gap is that it doesn't say how confident or structured the classification answer is when multiple rules could apply.

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

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

Two sentences, front-loaded with the core question and then the mechanism and sourcing. The mid-sentence parenthetical listing s17(2) categories makes the first sentence long, but it earns its place by showing the input-VAT scope concretely.

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, and the description compensates by telling the agent what comes back: a classification grounded in a rules table with the governing VAT Act section, optional related official material, and an explicit no-match statement. For a three-parameter read-only classifier, nothing needed 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?

Schema coverage is 100%, with side and include_library fully documented including the default, so the schema carries most of the weight. The description adds only indirect meaning: the s17(2) list signals what the purchase side covers, and "related official material from the GetLawED library" clarifies what include_library actually retrieves. 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?

The description opens with the exact question answered (standard-rated / zero-rated / exempt, plus input-VAT claimability), naming the VAT Act and the s17(2) denial categories. That verb-plus-resource framing separates it cleanly from the sibling sa_vat_calculate, which computes amounts rather than classifying a supply.

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 concrete triggering examples ("client lunch at a restaurant", "club subscriptions", "motor cars") and the two angles — output treatment vs input claim — that map to the side parameter. It does not, however, explicitly name sa_vat_calculate as the tool to use once classification is known, so the routing between siblings is left implicit.

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