SA Crypto Tax Rules

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

Annotations already establish readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds substantive behavioral context beyond that: it names the five SARS/court factors the reasoning weighs and explicitly frames the result as a heuristic indicator rather than a ruling, which shapes how the agent should present and trust the output.

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, both load-bearing: the first defines the answer and its tax consequences, the second lists the deciding factors and bounds the reliability of the result. The caveat is placed where it matters, at the end, with 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 must convey what comes back, and it does: a reasoned indication along a capital/revenue spectrum with a stated tax consequence on each side. For a six-parameter advisory tool with safety annotations already in place, this is close to complete; only pagination-style operational details are absent, and they do not apply.

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 still earns credit by explaining why these inputs matter — intention, holding period, trading frequency, funding and business-like operation are the factors SARS and the courts weigh — giving the agent a rationale for populating each field rather than treating them as arbitrary switches.

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 classification task: deciding whether a South African taxpayer's crypto gains are capital (CGT, 40% inclusion) or revenue (income). That is a clear verb-plus-resource, and the jurisprudential framing separates it in spirit from the numeric siblings. It never names those siblings, so there is no explicit routing.

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 closing caveat 'An indicator for discussion, not a ruling' tells the agent this is advisory output rather than a definitive computation, which is real usage context. It does not say when to call this instead of crypto_tax_estimate or crypto_tax_rules, so selection still relies on inference from the sibling names.

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, the description discloses the calculation method, SARS treatment rules, tax-year boundaries, and the main return categories, including per-disposal proceeds, base cost, gain, yearly totals, income, and remaining holdings. It still omits some behavioral details such as rounding, error handling, and how same-day ordering is managed, though the schema covers ordering.

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

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

The description is front-loaded, uses two efficient sentences, and every clause contributes relevant scope or output information. The parenthetical note on SARS accepting FIFO but not weighted average earns its place because it explains the chosen method.

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, so the description appropriately explains the main return categories and optional tax estimate. For a nested transaction-based calculator, it is largely complete, though it could say more about input assumptions such as rand valuation and handling of incomplete history, which the schema only partly covers.

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 input schema already documents the transaction fields, treatment enum, and optional tax-estimate object thoroughly. The description adds useful framing about which transaction types are accepted, but it does not provide parameter-level semantics beyond what the schema already supplies.

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: it calculates South African capital gains and losses on crypto from a transaction list using FIFO. It also defines the tax-year scope and output categories, so an agent can distinguish it from a simple tax estimator or a capital-versus-revenue classifier.

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 clear that this tool performs the full FIFO gains calculation and can optionally estimate tax, which implies it is the right choice when disposal-level gains are needed. However, it does not explicitly say when to use this instead of crypto_tax_estimate or crypto_capital_or_revenue, and it 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 declare a read-only, closed-world computation, so the safety bar is low; the description nonetheless adds real behavioural context by disclosing the calculation methodology (annual exclusion, 40%/80% inclusion rate, tax tables, age rebates) and what the result contains (tax with and without crypto, marginal rate, carry-forward loss). It does not state that results are an estimate only, nor how non-default tax years or unsupported cases are handled.

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 purpose is front-loaded in the opening clause and every subsequent clause carries substantive information (exclusion, inclusion rate, outputs). It is one long run-on sentence, which makes it harder to scan than a short structured breakdown would 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?

With no output schema, the description usefully spells out the return components, and the non-required parameters with defaults are all documented in the schema. What is missing is a caveat about the estimate's reliability and how the caller should obtain the capital-gain inputs, but overall it is sufficient to invoke the tool 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 already carries its own meaning, including defaults and the note that the annual exclusion is shared with other capital gains. The description adds domain framing but no parameter-level 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 names a specific verb ('Estimates') and a precisely scoped resource ('the extra South African income tax caused by crypto in one tax year'), including the taxpayer types covered. This is clearly distinguishable from the sibling lookup tool (crypto_tax_rules) and the classification/FIFO helpers, which do not produce a liability figure.

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: an agent can infer it should call this when it wants a tax liability estimate rather than rules or raw gains. There is no explicit when-not guidance, no mention that crypto_gains_fifo or crypto_capital_or_revenue should be run first to derive the gain figures this tool consumes, and no statement of prerequisites such as prior-year assessed losses.

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 the safety profile is covered; the description adds real value by disclosing that the payload is a static reference corpus and by naming a non-obvious rule (FIFO or specific identification, not weighted average). It stops short of saying whether the data is versioned/snapshot per year or what is returned when a tax year has no published rules.

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 a colon-introduced content list; nothing is padded or redundant. It is dense and long but every clause names a distinct returned item, so the length is earned rather than wasteful.

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 a single trivial parameter, the description carries the burden of telling the agent what comes back, and it does so thoroughly by enumerating the rule categories. The only material gap is behavior at the edges — unsupported or future tax years and whether the response reflects a dated snapshot.

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% — the tax_year property already explains that it is the year the tax year ends and defaults to the current tax year. The description restates the same idea ('for a tax year') without adding format, valid range, or fallback behavior, 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 opens with a specific verb and resource ('Returns the South African crypto tax rules for a tax year') and then enumerates the exact contents returned (income tax table, CGT exclusion, inclusion rates, cost methods, treatment of swaps/gifts, CARF reporting). This clearly distinguishes it from siblings that compute figures (crypto_tax_estimate, crypto_gains_fifo) — this one is a reference lookup, not a calculation.

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: an agent can infer this is the tool to consult for rules and rates rather than to compute a liability. There is no explicit 'use this when…' statement, no named alternative (e.g. 'for an actual liability, use crypto_tax_estimate'), and no note on what to do for years outside the supported range.

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 context beyond the annotations: 'Free to call' signals no call-budget cost, and 'We review these every week and build the most-requested data first' discloses that this is an asynchronous request with no immediate data returned. Nothing contradicts readOnlyHint=false (a submission does create a record) or openWorldHint=false; auth and rate-limit details are absent but low-risk here.

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 cost signal and then the qualifying condition, then the outcome. No restatement of the tool name and no wasted clauses.

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 fully documented, no-output-schema submission tool, the description covers purpose, trigger and what happens after submission. It could be slightly more complete by stating that no data is returned synchronously, but the weekly-review sentence conveys that implicitly.

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 schema already explains need, region and context fully. The description reinforces the one-sentence constraint on the required field but adds no meaning beyond the schema for the optional region and context parameters, 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 action (describe a missing data need) and resource (South African cost, rate, rule, price or place not covered), and explicitly frames itself as the fallback when the sibling calculators don't cover a need. It is immediately distinguishable from bond_repayment, municipal_rates and the other siblings, which are lookups rather than submissions.

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: use this when needed South African data is not provided by 'none of these tools,' and enumerates the kinds of gaps that qualify. It does not name the specific sibling domains, so an agent still has to reason about what the siblings already cover before deciding to fall back here.

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