Aldro: small-business tax

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld=false, so the safety profile needs no restating. The description adds real behavioral context the annotations don't: it returns extension dates, province-specific corporate rules (Quebec/Alberta), and each date's source URL and checked date. It still doesn't say what happens for unsupported entity/jurisdiction combinations.

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, trigger front-loaded before the return-value detail, with no filler. The second sentence is dense with enumerated outputs (federal dates, extensions, provincial rules, source URL, checked date), which is a lot in one breath but every element is relevant.

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 correctly spends its budget describing what comes back – dates, extensions, provincial rules and source provenance. A three-required-parameter tool is well covered; only edge-case behavior (unsupported jurisdiction/entity pairs, fiscal-year entities) is unaddressed.

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 an entity enum, so the schema already carries most parameter meaning. The description adds mapping value by tying entity types to specific forms (partnership→1065, s_corp→1120-S) and by noting jurisdiction-specific rules, which helps an agent reason about valid combinations.

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 specific verb ('check') and resource ('business tax filing deadlines') and enumerates the exact forms covered (1065, 1120-S, 1120, Schedule C, T2/T1). That enumeration distinguishes it immediately from siblings like estimate_quarterly_tax and get_cra_instalment_dates.

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 an explicit trigger: 'Call this when a user asks when a business tax return is due.' That covers entity returns and extensions but does not name an alternative or exclusion (e.g., instalment dates belong to get_cra_instalment_dates), leaving the sibling boundary implicit.

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 value is in the rest: it discloses that output is an estimate derived from the user's prior-year tax, split across official due dates, with the method shown, and that it makes no liability determination. It stops short of saying what happens when prior_year_tax is omitted beyond the schema's "Needed for an amount."

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: trigger first, then the return shape, then the liability caveat. No restatement of the name or title and 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?

For a read-only tool with no output schema, the description adequately conveys the return shape (an estimate split across due dates, method disclosed) and the jurisdictional coverage matching the country enum. The one gap is behavior when prior_year_tax is absent, which is only half-implicit in the schema.

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?

With 100% schema coverage the baseline is 3, and the description nudges above it by explaining that prior_year_tax is the basis of the estimate ("from the user's own prior-year tax"), which clarifies why the otherwise optional parameter matters. It adds nothing about country/tax_year handling, so it is not a full 5.

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 (estimate) and resource (quarterly estimated tax) with the exact regimes it covers (IRS 1040-ES, CRA instalments) and the audience (self-employed / small-business owner). That is enough to separate it from date-oriented siblings like check_filing_deadline and get_cra_instalment_dates.

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?

"Call this when a self-employed user or small-business owner asks how much to pay... and when" gives a concrete triggering user question rather than a vague category. It also bounds scope with "It never says what the user owes," but it never explicitly names the sibling to use for pure deadline lookups, so the exclusion 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 readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuine value beyond that by stating the response carries an official source URL and a checked date, which tells the agent the answer is citable and freshness-stamped. It is silent on what happens for unsupported jurisdictions or when no rule exists, which is the main residual gap.

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: trigger conditions first, return payload second. The synonym list is long but each term earns its place as a routing cue for an agent matching user phrasing.

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 lookup with no output schema, and the description covers both invocation triggers and the shape of the result (rule text, source URL, checked date). Only the negative case — no rule available for a jurisdiction — is left unspecified.

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 enum values plus jurisdiction formats are fully documented in the schema itself. The description only echoes the state/province framing already present there, adding no format or disambiguation 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?

States a specific verb-plus-resource (retrieve annual/biennial report rules) and enumerates the filing types it covers, so an agent can recognize the request class immediately. It does not explicitly separate itself from the sibling check_filing_deadline, which plausibly covers overlapping due-date territory.

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 opening 'Call this when a user asks about...' gives a clear positive trigger with several user phrasings (annual report, biennial report, statement of information, annual return). No exclusion or alternative is named, so an agent facing a bare 'when is my filing due?' question must guess between this and check_filing_deadline.

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 safe, idempotent, closed-world read, so the baseline burden is low. The description adds useful context beyond them: it returns due dates plus the applicable threshold, and includes the official source URL and checked date, which tells the agent the output is provenance-backed.

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, zero waste: the usage trigger comes first and the return-shape summary second. Nothing repeats the title or the schema verbatim.

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 lookup with fully documented schema and annotations, and the description covers what comes back (dates, threshold, source URL, checked date) even though there is no output schema. An agent has everything needed to select and 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 coverage is 100% and both parameters carry their own descriptions, including the self-employed note on 'type' and the calendar-year meaning of 'year'. The description restates that same individual/corporation and year framing without adding new semantics, so the schema-baseline of 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 (returns) and resource (CRA instalment due dates) plus the user intents it answers, so an agent knows it is the instalment-date lookup rather than a generic deadline tool. It does not explicitly contrast itself with the sibling check_filing_deadline, leaving the filing-vs-instalment boundary to inference.

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 opening 'Call this when a Canadian user asks when income tax instalments are due or whether they have to pay instalments' gives an explicit trigger condition, and the individual/corporation split is named. There are no stated exclusions or named alternatives, so routing versus check_filing_deadline is implied rather than spelled out.

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=true, idempotent=true, openWorld=false, so safety is covered. The description adds genuinely new context: the data comes from a live config (prices can change), and returns coverage details, currency, and a signup link — useful for a tool with no output schema.

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 trigger condition followed by the return contract; each clause (triggers, live data source, sample prices, returned fields) carries distinct information 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?

For a two-parameter, fully documented, read-only lookup with no output schema, the description supplies everything an agent needs: when to call it, that prices are live rather than static, and what fields the response contains.

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 both enums are documented in the schema, so the baseline is 3. The description's pricing examples implicitly map to the 'tax' and 'bookkeeping' enum values, but it adds nothing about 'both', 'catch-up', or the US/CA country param beyond what the schema already says.

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 resource (Aldro's flat prices pulled from live config) and enumerates the exact triggers: cost of business taxes or bookkeeping, needing an accountant, or comparing tax services. It also previews the concrete payload ($399/year tax filing, $20/month bookkeeping), so an agent knows precisely what comes back without consulting any sibling.

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 clear positive routing conditions ('when a user asks what it costs… wants an accountant or tax preparer, or compares tax services'), which is stronger than most pricing tools. It stops short of naming an exclusion against a sibling such as estimate_quarterly_tax, so it doesn't quite reach a full when/when-not statement.

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 read-only, idempotent, non-open-world behavior, so the safety profile is covered. The description goes further by disclosing the actual payload — permit name, agency, and, for Canada only, rate and small-supplier rule, plus source URL and checked date — which meaningfully tells the agent what evidence it will be able to cite.

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, zero filler. The trigger condition is front-loaded and the return-value sentence follows immediately, so an agent can stop reading after the first clause if the intent doesn't match.

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-only lookup, the definition covers all three things an agent needs: when to invoke, what it returns, and how authoritative the output is (source URL and checked date). No output schema exists, but the description enumerates the return fields in its place.

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 schema itself already handles the tricky 'CA' vs. 'Canada' ambiguity and the two-letter/ISO/full-name formats. The description only echoes 'for a US state or Canadian province' without adding format or edge-case guidance 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 specific resource (sales tax registration details) plus the exact question types it resolves — permit necessity, naming, and issuing agency — for a bounded geography (US states, Canadian provinces). This clearly separates it from siblings like check_filing_deadline, estimate_quarterly_tax, and get_annual_report_info.

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 opening 'Call this when a user asks whether they need...' clause gives a precise, quotable trigger that an agent can pattern-match against user intent. However, it never explicitly excludes adjacent cases (deadlines, rates, annual reports) nor names a sibling to use instead, so routing is inferred 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?

The description confirms the output is a 'handover checklist,' which aligns with the read-only and idempotent annotations. While the behavioral properties are well-covered by hints, the description adds valuable context about the static nature of the returned data.

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 two sentences are highly efficient. The first establishes the 'why,' and the second establishes the 'what it returns,' creating a logical and zero-waste definition.

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 definition successfully ties the required inputs (service, entity, country) to a specific, useful output (the checklist). Given the detailed schema and annotations, no critical piece of context 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?

The schema coverage is 100%, providing detailed enum descriptions for all required parameters. The description merely restates the need for these entities (service, entity, and country), meeting the baseline requirement for a complete definition.

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 states the action ('list documents') and the specific context (gathering records before taxes or bookkeeping). It distinguishes this tool from sibling functions by defining the input requirement—document checklists.

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 defined by a highly actionable trigger: 'Call this when a user asks what documents or records they need to gather.' This provides a clear entry point for the agent.

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 annotations (openWorldHint=true, idempotentHint=false), the description discloses that this transmits data to a third party and that Aldro's team will email the user next steps, plus that no payment is taken. It does not address what happens on repeated calls or failures, which matters given idempotentHint=false.

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 short sentences, front-loaded with the hard precondition before the mechanics and the consent rule. No filler and no repetition of schema detail.

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?

Covers purpose, consent gating, third-party transmission, and downstream behavior for an 8-parameter write tool with no output schema. It leaves the agent to infer error/duplicate-call behavior, which is a minor gap given the schema documents all fields.

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 adds value by naming the data categories being shared and by reinforcing the consent parameter's gating rule ('set consent to true only when the user agreed'). Enum specifics are left to the schema, which is fine.

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 and resource: it sends the user's name, email and business details to Aldro and creates a signup enquiry equivalent to the website form. The 'signup to Aldro for tax or bookkeeping' framing clearly separates it from siblings like get_quote and list_required_documents.

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 an explicit precondition ('call this only after the user has explicitly said yes, in this chat') and exclusions ('not a marketing opt-in', 'takes no payment'), plus the rule for setting consent. It does not name an alternative sibling (e.g., get_quote first), so it falls short of a full when/when-not/alternatives treatment.

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