Tallyfern Rates (Canada)

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

Annotations already establish this as a safe, idempotent, closed-world read. The description adds real context beyond them: the 2026 default with 2025 also available, the two-tier kilometre structure (first 5,000 km and after), and the province-vs-territory rate split. It does not mention rate publication/update cadence or limits, 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?

A single dense sentence with the core resource and defaults front-loaded and the optional calculation tacked on last. No wasted clauses, though the parenthetical and tier list make it slightly heavy to parse.

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 an output schema present, return values need not be described, and the description covers the dimensions an agent needs: year options, rate tiers, and province/territory variation. The one gap is that it never states what happens when province is omitted, which matters for a tool with zero required 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 coverage is 100%, so the baseline is 3. The description goes slightly beyond the schema by signaling that the year defaults to 2026 and that province/territory choice materially changes the rate tiers, which is a meaningful semantic hint about why the province parameter exists.

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 (CRA reasonable per-kilometre allowance rates) with clear scope: employer-paid vehicle allowances, 2025/2026, first 5,000 km vs after, provinces vs territories. This is distinguishable from siblings like cra_meal_travel_allowance or the GST/HST rate tools 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?

The phrase 'Optionally calculates the allowance for a number of business kilometres' implies when the kilometres parameter applies, but there is no explicit when-to-use guidance, no when-not-to-use, and no routing to alternative siblings. Usage is inferable 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 establish the safe read-only, idempotent, closed-world profile, so the description only needs to add context beyond that. It does add useful traits: the rates are for the latest published tax year, and amounts are computed only optionally, which clarifies that a bare call is a valid lookup.

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 that lead with the resource and rate shape before scoping and the optional calculation. Dense but each clause carries information; only 'Optionally calculates amounts' is slightly vague about what triggers calculation.

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?

An output schema exists, so return values need not be explained. Combined with the applicability scope, tax-year currency note, and the optional-parameter behavior, 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 each of the four parameters is already documented, including the dependency that kilometres needs province and that days caps meals at the daily maximum. The description adds little beyond this, so the baseline of 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?

Names a specific resource (CRA simplified-method meal and vehicle rates) and states the shape of the returned data (flat meal rate per meal, daily maximum, cents/km by province/territory). It does not explicitly differentiate from the sibling cra_automobile_allowance_rate, whose subject matter overlaps with the vehicle portion, leaving a potential ambiguity.

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 applicability scope — moving expenses, northern residents deductions, medical travel — plus an explicit exclusion (not employer per-diems), which is real when-to-use guidance. It stops short of naming the sibling tools or stating when a different rate tool should be chosen instead.

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 safety/read-only/idempotent behavior. The description adds that it returns the CRA-listed PST/QST 'for reference' and cites the source table, which is useful provenance. It doesn't note caching/currency beyond 'current', so it's modest added 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?

Two sentences, front-loaded with the core operation, no filler. Source citation is compact.

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 an output schema present, the return values need not be described. The description covers scope, optional province, and PST/QST reference, but doesn't explain what happens for territories or mixed federal/provincial treatment in enough detail.

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 single parameter is fully described with format examples, so the schema does the heavy lifting. The description's '(or all 13)' does clarify the optional/no-args behavior, which is a slight value add over 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?

States a specific verb/resource: 'Current GST/HST rate for a Canadian province or territory (or all 13).' It also disambiguates the sibling tools by being clearly the rate-lookup, not the small-supplier check or allowance tools.

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 looking up a rate by province, and 'or all 13' signals the no-arg case. It doesn't explicitly say when to use this versus gst_hst_small_supplier_check, but the purpose is distinct enough that an agent can route 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 this a safe, read-only, idempotent, closed-world computation, so the safety bar is low. The description goes beyond that by enumerating the four outputs produced (must-register determination, cessation timing, effective registration date, next-quarter headroom) and the scope boundary on entity type. It does not mention edge-case behavior, but for a deterministic calculation this is adequate.

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 action and immediately followed by the concrete outputs and the scope caveat. Dense but every clause carries information; the parenthetical naming the two tests is slightly heavy but justified.

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?

An output schema exists, so return values need not be spelled out, yet the description still summarizes them helpfully. Annotations cover the safety profile, and the description covers the tests applied, the input domain, and the entity-type limitation. Nothing material for correct invocation 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 both parameters carry their own descriptions, including the definition of taxable revenue and the quarter numbering. The description adds conceptual framing ('taxable revenue by calendar quarter') but no syntax or format 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?

States a specific operation (apply the CRA's $30,000 small-supplier tests), the exact inputs it operates on (taxable revenue by calendar quarter), and the precise outputs (registration requirement, cessation date, effective registration date, headroom). This is clearly distinguishable from the sibling tools, which are rate lookups and allowance calculators.

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 establishes clear context (determining GST/HST registration status via the two small-supplier tests) and an explicit exclusion — charities and public service bodies are out of scope. It doesn't name sibling tools or conditions for choosing between them, but none of the siblings overlap functionally, so the gap is minor.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds that it is 'plain-language' with 'CRA sources', which signals a curated static reference, but says nothing about staleness, jurisdiction limits, or how the facts are presented beyond the annotation coverage.

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 zero filler; the covered topics are listed compactly and the sourcing note is appended efficiently.

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 parameters and an output schema present, the description needn't explain return values, and it enumerates the substantive topics a caller would expect. The only gap is not routing the agent between this reference and the more specific sibling 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?

Zero parameters and 100% schema coverage, so there is nothing for the description to disambiguate. Baseline 4 applies for a parameterless 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 names a clear resource ('plain-language basics for Ontario businesses') and enumerates the exact topics covered: 13% HST rate, $30,000 threshold, 29-day deadline, place-of-supply rule. That enumeration partly differentiates it from siblings like gst_hst_rate_by_province and gst_hst_small_supplier_check, though it never explicitly positions itself against 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?

There is no statement of when to use this tool versus the sibling rate/supplier tools, nor any exclusions. The agent must infer that this is a general reference while the siblings perform specific lookups or checks, which is not spelled out.

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