OpenAccountants

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

Annotations already declare readOnly/idempotent/non-destructive/non-open-world, and the description layers on real behavior: the enumerated outcome set, that 'cannot_determine' is a valid result, the 'draft' accountant-confirmation flag, and that missing prior_year yields 'review'. This is substantial context beyond the annotations.

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 the core question and jurisdiction scope, then dense but purposeful sentences covering outcomes, prior_year, and the draft caveat. Slightly long, but nearly every clause carries actionable information.

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 9-parameter tool with a nested prior_year object and an output schema, the description covers outcomes, edge cases (unsupported jurisdiction, wrong currency, group membership), and the human-review path. Nothing an agent needs to call it correctly 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%, so the baseline is 3; the description adds rationale the schema lacks—why prior_year matters (two-consecutive-year tests) and the currency-must-match-regime rule with 'convert first, never guess a rate'. It maps parameters to the regulatory logic rather than restating types.

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 question it answers ('does my company need an audit?') scoped to named jurisdictions (MT Article 185(2), GB small-company thresholds). This is clearly distinguishable from every sibling, which are list/get/search utilities rather than determination engines.

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 strong conditional guidance: pass prior_year for two-consecutive-year tests, group_member forces 'review', non-private shapes route to a human, and 'use the determination as returned, not thresholds from memory'. It lacks explicit sibling alternatives, but none of the listed siblings are substitutes for this check.

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 the safety profile is covered. The description adds genuinely new context: results come from the OpenAccountants tax calendar, include both upcoming dates and recurring rhythms, and that the response marks jurisdiction_source.

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-loads the resource and scope, then uses compact example queries to convey intent efficiently. Slightly dense but every clause carries information; 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?

An output schema exists, so return values need not be detailed, yet the description still summarizes the output shape. For a two-parameter read tool this covers everything an agent needs 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 coverage is 100%, and the description's jurisdiction note ('can omit jurisdiction') largely restates what the schema already documents. The pointer to the jurisdiction_source response field is a small addition, but the schema is doing most of the work.

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 ('Filing and payment deadlines for a country or US state') with example phrasings that map directly onto the tool's intent. No sibling in the list competes for this operation, so the agent can distinguish it immediately.

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 illustrative queries ('when is my tax return due', 'when do I file VAT') make the intended use unambiguous, and it notes that signed-in users with a saved home jurisdiction can omit the parameter. It stops short of naming alternatives or explicit exclusions, but none are needed since no sibling overlaps.

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 a closed world, so safety is covered. The description adds genuinely new behavioral context: the data mirrors the website, incomplete scope makes the total provisional, separately quoted services require confirmation, and no engagement is created. It does not mention caching/staleness or rate limits, which keeps it at a 4 rather than 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?

Five compact sentences, front-loaded with the invocation trigger before the payload description, and no filler. The one slight inefficiency is that the return-value inventory is enumerated at length even though an output schema exists, so a sentence or two partly duplicates structured data.

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 pricing lookup with full schema coverage and an output schema, the description supplies everything needed: when to invoke, what is returned, the provisional-total caveat, the confirmation requirement for separately quoted services, and the explicit statement that no engagement is created. Nothing an agent needs in order to call it correctly 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%, so every parameter including the reason/current_fee/jurisdiction logging semantics is already documented in the schema. The description's only added parameter guidance is 'match the client's scope to the listed prices' and the provisional-total caveat, which is useful but marginal. Baseline 3 applies when the schema does the heavy lifting.

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 ('Get an OpenAccountants fee estimate') and then enumerates exactly what comes back: published plans, service prices, limits, market exceptions, hourly rate, plus engagement process and contact details. No sibling tool deals with pricing, so an agent can route to it unambiguously from the name and description alone.

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 trigger conditions ('only when the user asks what OpenAccountants charges, requests a quote, or asks whether their current fee is fair') and a negative boundary ('does not create an engagement'), which implicitly separates it from share_with_openaccountants/start. It stops short of naming an alternative tool for adjacent intents, so it is clear context rather than full when/when-not/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 read-only, idempotent, non-destructive, closed-world behavior, but the description adds real value by enumerating the returned artifacts (rules, method, quality tier, reviewing accountant, section_index of non-inlined sections, provenance footer) and the instruction to keep the footer with the answer. This is useful operational guidance beyond the structured fields.

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 dense but well-front-loaded sentence: the operation and its input source come first, then the return contents. No filler, no restating of the title.

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 and rich annotations covering the safety profile, the description supplies the remaining actionable context: where the slug comes from, what the payload contains, and the provenance-footer handling. An agent has everything needed to call and use the result 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%, so the baseline is 3; the description modestly exceeds it by tracing the slug's origin to start/search_skills/search_rules. The optional 'reason' parameter is not described in the tool description, though the schema documents it.

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 ('Open a skill by slug') plus the reason for doing so ('to answer the user's question'), and names the sibling tools that produce the slug. It is readily distinguishable from get_skill_sections (returns indexed sections) and search_skills (finds slugs).

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?

Explicitly tells the agent where the required slug comes from (start, search_skills, search_rules), which is the key usage prerequisite. It does not state when to prefer this over get_skill_sections or when not to call it, so it stops short of full when/when-not guidance.

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, destructiveHint=false and openWorldHint=false, so safety and repeatability are covered structurally. The description adds the useful cross-tool detail that sections are addressed by the indexes get_skill reported, but says nothing about ordering, limits, or behavior when a slug or index does not exist.

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 relationship to get_skill and then the parameter behavior. No filler, no restatement 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?

An output schema exists, so return values need not be described, and the annotations carry the safety profile for this simple read tool. The only real gap is the unaddressed section_indices parameter, which is minor for a three-parameter read operation.

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. The description adds genuine cross-tool semantics by tying section_index to get_skill's section_index list, but it never mentions the section_indices (plural) parameter, leaving one of the three parameters unexplained in prose.

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 ('fetch sections') and immediately positions itself relative to the sibling get_skill as a follow-up, so an agent can distinguish it from get_skill without opening either schema. It also defines scope: sections that were listed as not inlined.

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?

Explicitly names the trigger condition (after get_skill, when sections were flagged as not inlined) and gives the routing rule for the optional parameter: pass section_index for one section, omit to get all. The alternative (get_skill's inlined content) is implicitly and clearly excluded.

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). The description adds scope semantics beyond that: only jurisdictions with *published* skills are returned, plus what each entry contains (counts and named lead accountant). It doesn't mention result size or any limits, but for a no-argument read tool this is solid 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 dense sentences with zero filler, the trigger question leading and the payload described second. Every clause carries information an agent can act on.

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-value structure needn't be explained, yet the description still summarizes the payload shape (code, skill count, reviewed count, lead accountant). Nothing an agent needs to invoke this zero-arg, read-only listing tool 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 tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate beyond confirming it is argument-free.

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 and pins down the exact scope: "Returns every jurisdiction with published skills," including the code formats (ISO 2, US-XX, Canadian provinces). It is clearly separable from the list_skills/search_skills siblings, which operate on skills rather than coverage geography.

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?

Frames usage around two concrete user questions ("which countries do you cover?", "what is there for [country]?"), which is a clear trigger context. It does not, however, name alternative tools or state when NOT to use it versus list_skills/search_skills for country-scoped lookups.

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, so the safety profile is covered. The description adds real context beyond that: it takes no arguments, it returns only *live* jurisdiction values and a *sample* of topics (not exhaustive), and it includes defaults. That last detail matters to an agent deciding whether the list is authoritative.

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 short sentences, front-loaded with the resource and payoff, then the usage rule. No repetition of the title and no filler; every clause carries information.

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 the description need not explain return shape, and it still names the facet categories and the 'defaults' it returns. For a zero-argument read-only helper this is complete coverage of what an agent needs to select and call it.

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 zero parameters the baseline is 4, and the description reinforces it with 'Takes no arguments,' which matches the empty schema. No further parameter semantics exist to document, so there is nothing more the description could add.

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 ('lists the values you can filter on') and enumerates the facet dimensions it covers (jurisdictions, domains, roles, rule kinds, statuses, tax years, topics). It also positions itself explicitly as a helper for the sibling tool search_rules, so an agent can distinguish it from list_jurisdictions and the other list_* tools without opening 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?

Gives an explicit trigger ('Use it when unsure of a filter value rather than guessing') and names the tool it feeds into (search_rules). The when-not case is implied and unambiguous: if you already know the filter value, go straight to search_rules.

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 the safety profile is covered. The description adds useful behavior beyond that: results carry quality tier and verification status, and pagination is bounded (default 100, max 200) with offset/next_offset paging. It does not, however, describe ordering or what happens when no filter is supplied.

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 sentences, front-loaded with the core scope, then the routing alternative, then filters and pagination. Every sentence carries new information with no padding.

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 no explanation, and the description covers scope, filters, the sibling alternative, and pagination limits. The only thin spot is not stating behavior when zero filters are passed, but nothing critical 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%, so all six parameters are already documented, including the legacy-category fallback and role/domain value lists. The description restates the role values and the pagination dance (offset/next_offset) but adds no semantics the schema lacks, so baseline 3 is right.

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 ('Browse the skills') with scope narrowed to one jurisdiction or domain, and explicitly names the sibling it is not (search_skills). An agent can distinguish this from search_skills, get_skill, and list_jurisdictions 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?

Gives the routing rule explicitly: browsing a jurisdiction/domain, use this; 'For a specific topic, search_skills is quicker.' It also names the filter dimensions and the pagination contract, so both when-to-use and when-not-to-use are covered.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds the substance of what is returned (credentials, covered jurisdictions), but says nothing about auth needs, rate limits, or whether the list is exhaustive; with an output schema present, this is adequate rather than rich.

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 user-facing intent before the technical return description, with no filler. The quoted-question opener is slightly rhetorical but earns its place by anchoring intent matching.

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 zero-required-param read tool with full annotation coverage and an output schema, the description supplies everything needed to select and call it. Only minor omissions (no mention of result ordering or scope of completeness) keep it from being fully complete.

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 single optional 'jurisdiction' parameter is fully documented as an ISO code filter in the schema. The description's mention of 'jurisdictions they cover' alludes to the dimension but adds 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?

Specific verb ('Returns... named licensed accountants') plus a precise resource and scope ('who have signed off on OpenAccountants jurisdictions'). The framing questions ('who reviewed this?') make the intent instantly matchable and clearly separate it from sibling list_* tools like list_jurisdictions and list_skills.

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 clear intent-based context via the two quoted user questions, which tells an agent when this tool applies. It does not, however, state when not to use it or name an alternative sibling for adjacent needs, so it stops short of full routing guidance.

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 (readOnly/idempotent/non-destructive), but the description adds substantial behavioral context beyond them: it returns a bundled markdown rule set plus official_source, GUIDANCE entries are text not values, figures are not certified current and should be confirmed against official_source, and the status:'verified' filter does NOT mean accountant-reviewed. These are non-obvious traits an agent would otherwise get wrong.

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?

Dense but front-loaded: the core capability and examples come first, then caveats. Every sentence carries information (skill routing, GUIDANCE tagging, verification caveats), though the description is on the long side and the parenthetical routing guidance is packed tightly.

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 a 12-parameter tool with an output schema and full annotation coverage, the description closes the remaining gaps: what is returned, what verification status means, and the reliability caveat about figures. An agent has everything needed to call and interpret 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%, so the baseline is 3. The description earns extra credit by clarifying semantics the schema does not: status:'verified' includes research-verified rules and excludes draft/needs_update/unsure, and default behavior returns all matching rules tagged with verification status. This directly disambiguates the status/statuses pair.

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 (look up) and resource (tax rates, thresholds and rules) with concrete query examples in multiple jurisdictions. It also contrasts itself with search_skills/get_skill, so an agent can distinguish it from siblings 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?

Explicitly routes the agent: 'For one specific figure in one jurisdiction a skill is often more complete (search_skills then get_skill)', explains why a figure may not appear here, and points to list_rule_facets for valid filter values. Both the when-to-use and the when-to-use-something-else cases are 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 cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description still adds useful non-schema context: results are slugs intended for get_skill, methods are run via start, and method skills carry an accountant-reviewed or source-cited trust tag.

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 sentences, front-loaded with the action and concrete query examples, then filters, then the return contract. Every clause carries information; nothing is padding.

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 detailed, yet the description still names the slug payload and the natural follow-up call. It covers the method/fact distinction and optional scoping, leaving only minor unstated details such as result limits or no-match behavior.

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%, including the content_type enum and its 'method' vs 'fact' semantics, so the schema already does the heavy lifting — baseline 3. The description restates jurisdiction/domain limiting and content_type='method' rather than adding syntax or matching behavior (e.g. partial-word or synonym matching) beyond it.

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 (find/search) and resource (tax skill) plus scope: keyword lookup of deductions, forms, regimes, rules. Concrete example queries make the retrieval target unambiguous, and it distinguishes itself from list_skills and search_rules by returning skill slugs rather than enumerating or matching rules.

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?

Explains when the optional filters apply ('limit to one jurisdiction or domain') and routes to the correct downstream tool in each case: get_skill to open a found slug, start to run a method. It lacks an explicit when-not-to-use statement (e.g. use list_skills to browse everything), so it stops short of the top tier.

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 destructiveHint=true, non-idempotent, closed-world, and the description adds substantial context beyond them: anonymization requirements, that the request is saved and the team notified, that a booking link is returned, and the free-call/paid-work distinction. It does not, however, reconcile the closed-world annotation with a tool that transmits data to an external team, so it falls short of full transparency.

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 the triggering condition and the two-mode structure, and every sentence carries operational weight. It is dense and on the long side for a single tool, which keeps it just short of ideal.

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 triggers, exclusions, mode semantics, required supporting data, external effect, cost model, and call-frequency limits. An output schema exists and the description defers to it while still noting the booking link, so nothing an agent needs 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?

With 100% schema coverage the baseline is 3, and the description earns above that by explaining the mode gating (which parameters are 'Review only' and jointly required for request_review) and by emphasizing the anonymization constraint on `note`. It largely restates rather than expanding the schema's per-field text.

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: sending the user's feedback or a request-for-human to OpenAccountants. It names its two modes (`note` and `request_review`) and its trigger phrases, so it is unmistakable against siblings like get_quote or start_help.

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 the explicit gating condition ('Only when the user asks'), lists the typical utterances that qualify, and explicitly excludes a near-miss ('a question about whether your own answer is right is not such a request'). It also bounds frequency ('at most once per user request; not as a routine closing step').

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 read-only/idempotent annotations, the description discloses non-obvious behavior: it may infer jurisdiction and report that via `jurisdiction_source`, it returns either `skills_to_load` or a clarifying request, and where no skill exists it returns a `research_brief` naming official sources. Coverage limits (190+ jurisdictions) and the fallback path are stated, which annotations alone would not 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?

The action directive and the key parameters are front-loaded, and every sentence carries routing or behavioral information. It is on the long side because of the long example list of question phrasings, which is useful but slightly padded.

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 an entry-point router with an output schema, an optional-reason field and clarifying-question behavior, the description covers purpose, inputs, inference rules, next steps and fallback. Nothing an agent needs to invoke it correctly 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%, so the baseline is 3, but the description adds real meaning: jurisdiction accepts ISO codes, US state codes or names ('DE', 'US-TX', 'Florida'), and it explains the inference rule for omitted jurisdiction. It also motivates taxpayer_type by the forking return-prep workflows, though the detailed field-level semantics live in the schema.

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 action (route/answer a tax, VAT/GST, payroll or filing question) plus the resource and the scoping constraint ('about a country or US state'), and positions itself ahead of siblings by saying 'call this first'. An agent can distinguish it from get_skill, search_skills or list_jurisdictions 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?

It states when to use it ('call this first for any tax... question'), names the concrete next step ('Returns the skills to read next (`skills_to_load`, open each with get_skill)'), and explains the alternative outcome when input is missing ('or what is still needed, usually the country'). Routing is explicit rather than inferred.

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 destructiveHint=false, so the safety profile is covered. The description still adds real behavioral context beyond them: the response branch depends on sign-in/approval status, yielding a personal briefing instead of the generic scoping questions. It stops short of describing error or unauthenticated behavior.

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 sentences with no filler: trigger condition first, arity second, return content and hand-off to `start` last. The routing information is front-loaded where an agent will read it.

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 restated, yet the description still summarizes the two possible response shapes. Combined with the explicit trigger, the next-step routing to `start`, and annotation-covered safety, nothing an agent needs to call this correctly 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?

There are zero parameters, so the baseline is 4. The description confirms 'Takes no arguments', which is consistent with the empty schema and prevents an agent from hunting for hidden inputs.

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 exactly what the tool returns — the two scoping questions plus available intents and jurisdictions, or a personalized `orientation` briefing for signed-in approved accountants. It is a specific verb+resource statement that an agent can distinguish from the sibling `start` 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?

It gives explicit trigger phrases ('what can you do?', 'how can you help me?', 'where do I start?') and names the alternative plus the condition that selects it: 'Once there is a question, call `start`.' Both when-to-use and when-not-to-use are covered.

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 safety (readOnly, idempotent, openWorld, non-destructive), but the description adds real behavior an agent needs: it hits an external EU registry, may return business name/address only where the authority discloses them, and reports registry downtime distinctly. The only gap is no mention of latency or rate limits on an external call.

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 the purpose, then usage, then coverage, then failure mode — a sensible information hierarchy. It runs four sentences and slightly overlaps the schema on country codes, but nothing is 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 an output schema present, return-value shape needn't be explained; the description instead covers what schema and annotations cannot: external-registry scope, country coverage and the downtime path. Nothing an agent needs before calling 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%, so both parameters are already documented with examples, prefix/spaces tolerance and the omission rule. The description adds only the coverage table ('EL' for Greece, 'XI' for Northern Ireland), which largely duplicates the schema's country_code text. 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?

Starts with a specific verb+resource ('Check live whether an EU VAT number is valid and registered') and immediately scopes it to the VIES registry. No sibling tool in the list does VAT validation, so it is unambiguously distinguishable.

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?

Names concrete trigger scenarios (B2B reverse charge, zero-rating an intra-EU sale, supplier onboarding) and gives an explicit exclusion with a fallback instruction: other countries including the UK are unsupported, so say live validation is not available rather than guessing.

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