Tallyfern Rates (Canada)

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered; the description adds real behavioral content: the 2026 default, the 5,000 km tier boundary, the province-vs-territory split, and the fact that calculation only happens if kilometres is supplied. It doesn't disclose whether the source is cached or versioned beyond the as-of date, which keeps 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?

Two front-loaded sentences with good density; the purpose and default year come first. The second sentence enumerates return fields that the output schema already covers, so it slightly overspends on that clause.

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?

Given an output schema and full annotation coverage, the description only needed to convey purpose, year options, tier behavior, and calc optionality — and it does all four. An agent can pick this tool and call it correctly with no open questions.

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, but the description adds genuine meaning the schema lacks: the 5,000 km tier threshold that makes kilometres behave differently above and below that value, and the province/territory duality behind the single region parameter. The default-year behavior is also restated usefully.

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 retrieves CRA reasonable per-kilometre allowance rates for employer-paid vehicle allowances — and names the exact structure of the data (first 5,000 km vs after, provinces vs territories). This clearly separates it from siblings like cra_meal_travel_allowance and gst_hst_rate_by_province without requiring schema inspection.

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 establishes context (employer-paid vehicle allowances) and states that 2026 is the default year with 2025 also available, plus that calculation is optional. What's missing is an explicit when-not-to-use pointer, e.g. routing meal/ Travel claims to cra_meal_travel_allowance rather than this tool.

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 safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add context — and it does: it discloses the calculation is optional, that results include scope notes, the source and an as-of date, and that the tax year is the latest published. It does not mention rate applicability dates or failure modes, but the added disclosure is meaningful.

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 what the rates are and who they apply to, then the optional calculation and return shape. Dense but no filler; slightly long in the trailing sentence enumerating return fields.

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 read-only, zero-required-parameter reference tool with full schema coverage, annotations and an output schema. The description supplies scope, applicability, province semantics and return-shape reassurance, leaving little an agent would need to guess.

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 each parameter already carries a description (including the 'caps meals at the daily maximum' and 'needs province' constraints). The description mostly restates that meals and vehicle amounts are optional calculations, adding little beyond the schema, so baseline 3 is correct.

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 simplified-method meal and vehicle rates, latest published tax year) with concrete detail: flat meal rate per meal, daily maximum, cents/km by province. It explicitly contrasts with employer per-diems, though it does not name the closest sibling, cra_automobile_allowance_rate, which an agent could confuse with the vehicle-rate portion.

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 applicability ('moving expenses, northern residents deductions and medical travel') and an explicit exclusion ('not to employer per-diems'), which is real when/when-not guidance. It stops short of naming an alternative tool for the excluded case, so the routing is incomplete but solid.

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 readOnly, idempotent, closed-world and non-destructive, so the safety bar is low; the description still adds real value by naming the upstream source (CRA's 'Charge and collect the GST/HST' table) and the as-of/effective-from dates, which tells the agent how fresh and authoritative the numbers are. It marks the PST/QST figure as CRA's reference value, a meaningful caveat.

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, front-loaded with the resource and scope, followed by provenance and return shape. The enumeration of returned fields overlaps with what the output schema already conveys, which is the only wasted effort.

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 single-parameter read tool with an output schema, the description covers scope, provenance, and data currency, which is what an agent needs to trust and call it. Minor omissions are how province names/codes are matched and that the PST/QST figure is informational only for provinces without HST.

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 lone parameter is already documented with examples, so the baseline would be 3. The description goes one step further by clarifying the omission behavior — no province yields all 13 rows — which the schema does not state.

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 the exact resource (current GST/HST rate per province/territory, all 13 or one) and adds the PST/QST reference value, so the agent knows precisely what data comes back. It doesn't explicitly separate itself from the nearby 'ontario_hst_basics' or 'gst_hst_small_supplier_check' siblings, leaving that differentiation to inference from the province scope.

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: the '(or all 13)' phrasing hints that omitting a province returns the full table, but there is no explicit statement of when to call this versus the Ontario-specific or small-supplier siblings. 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 already declare readOnly/idempotent/non-destructive/openWorld=false, and the description adds genuine context beyond them: the exact legal determinations computed, the excluded taxpayer population, and the structured output contents. It does not address behavior on short or gapped quarter sequences (beyond the schema note), or how a null triggering quarter should be read.

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 computation being performed and followed by the outputs. The parenthetical test qualifiers and the return-field enumeration are lengthy but each carries useful information; only the return-field list is partly recoverable from the output schema.

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 read-only calculation tool with an output schema, full annotation coverage, and 100% parameter documentation, the description supplies everything an agent needs: what is computed, who is in scope, and what comes back. No gaps remain that would affect correct invocation.

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 nested quarter objects document year, quarter, amount, and the contiguous-quarter requirement thoroughly. The description restates the taxable-revenue concept but adds nothing about the taxiOrRideshare override or the minimum-quarter requirements beyond what the schema already says, so the baseline 3 is correct.

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: applies the CRA $30,000 small-supplier tests (single quarter and four consecutive quarters) to taxable revenue by calendar quarter. It also names the outputs produced (registration requirement, small-supplier cessation, effective date, headroom), which distinguishes it cleanly from the sibling rate-lookup 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 gives clear context for use (quarterly taxable revenue, registration question) and an explicit exclusion: 'Most businesses only (not charities/public service bodies).' It does not name the sibling tools or state when to prefer them over this one, so it falls short of explicit alternative 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 and openWorldHint=false, so safety is covered. The description adds genuinely useful behavioral context beyond that: it is plain-language/low-authority in nature, cites CRA sources, and returns an as-of date that signals data freshness — a detail annotations cannot 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?

Two sentences, front-loaded with the audience and the covered facts, followed by the return shape. Dense but every clause names a distinct fact or field; slightly list-like, but 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?

With an output schema present the description need not restate return values, yet it adds a helpful gloss on the structuredContent fields and the as-of date. The only gap is the absent sibling/differentiation guidance against gst_hst_rate_by_province and gst_hst_small_supplier_check.

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 is 4. There is nothing to disambiguate, and the description correctly spends its words on output scope instead.

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 subject (Ontario HST basics for businesses) and enumerates the exact facts it covers — 13% rate, $30,000 threshold, 29-day registration deadline, place-of-supply rule — with CRA sourcing. It does not, however, explicitly differentiate itself from siblings like gst_hst_rate_by_province or gst_hst_small_supplier_check, which cover overlapping facts.

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 content scope (a plain-language primer on Ontario HST), but there is no explicit when-to-use guidance, no statement of when to prefer gst_hst_rate_by_province or gst_hst_small_supplier_check, and no mention of prerequisites or limits. An agent must infer the routing decision itself.

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