OpenAccountants

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description reveals critical behavioral traits: the tool is deterministic, returns a live verification envelope whose status must be surfaced, and treats 'cannot_determine' as a first-class outcome. It explains that 'review' is not an error when prior-year data is absent. No contradiction with 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?

The description is long but well-structured: it front-loads the core purpose with 'DETERMINISTIC check', then lists return components, coverage, and critical caveats. Its length is justified by the tool's complexity, though a few parenthetical asides (e.g., the exact 6 April 2025 eras) could be trimmed without losing essential value.

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 the tool's complexity (9 parameters, nested objects, output schema), the description is remarkably complete. It covers supported jurisdictions and era changes, explains each major outcome, the verification envelope, and edge cases (missing prior-year data, unsupported jurisdiction, wrong currency, changed facts). This is sufficient for an agent to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although the input schema already documents all parameters, the description adds substantial semantic value that the schema alone doesn't convey: the two-consecutive-years test requiring prior_year, the consequence of missing it, the currency-match requirement, and that entity_type 'non-private shapes route to a human' while group_member forces 'review'. This meaningfully exceeds 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?

The description states the tool's exact function: 'DETERMINISTIC check of whether a private limited company qualifies for statutory audit exemption'. It names the resource (audit exemption), the operation (check), and the input source (aggregate figures). It distinguishes itself from sibling tools like search_rules or validate_vat_number by focusing on the statutory determination.

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?

Provides explicit when-to-use and how-to-handle guidance: 'pass prior_year figures when available', 'without them a qualifying year returns review, not exempt; that is correct behaviour', and 'Never override the determination with training-data thresholds'. It also clarifies conditions for 'cannot_determine', effectively telling the agent when the tool is applicable and when to defer.

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, openWorldHint, idempotentHint, and destructiveHint, lowering the bar. The description adds context beyond annotations by naming the data source ('OpenAccountants tax calendar') and describing the jurisdiction fallback behavior for signed-in users, including the response marking jurisdiction_source. It doesn't contradict 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?

Three sentences, all purposeful. The first sentence front-loads the main purpose, the second gives usage triggers, and the third covers an important parameter detail. No wasted words or redundant restating of schema 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?

With rich annotations, a complete parameter schema, and an output schema present, the description covers all necessary context: what the tool returns, when to use it, and key behavioral nuances. It doesn't need to explain return values since the output schema handles that. It is complete for a tool of this complexity.

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% for both parameters, so the baseline is 3. The description adds meaning beyond schema by explaining that jurisdiction can be omitted for signed-in users and is filled from their profile, with the response indicating this via jurisdiction_source. This goes beyond the schema's basic description.

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 uses a specific verb and resource: 'Upcoming filing/payment deadlines and recurring filing rhythms... for a country or US state.' It clearly distinguishes this tool from siblings like search_rules or list_jurisdictions by focusing on deadlines from the OpenAccountants tax calendar. The scope is precise.

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 explicit when-to-use guidance: 'Use it whenever the user asks "when is X due", mentions a filing date, or when a heads-up about an imminent deadline would help.' It also notes that signed-in users can omit jurisdiction. However, it does not explicitly mention when not to use it or alternatives, though the context is clear enough.

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, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context: it returns only published skills (not drafts), always the current version, and includes a conditional verifier ('where accountant-verified'). This goes beyond what annotations alone provide.

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

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

The description is a single, well-structured sentence with no filler. It front-loads the core action and resource, then efficiently lists what is included, earning a perfect score.

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 description, combined with the rich annotations and an output schema, fully covers the tool's behavior for a simple single-item fetch. It names all key return components (markdown, tier, verifier, footer) and the 'published' constraint, leaving no critical gaps.

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%: both parameters (slug, reason) are fully described in the schema with examples and purpose. The description adds no additional parameter meaning, so the baseline score 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?

The description uses a specific verb 'Fetch' and names the exact resource 'published skill by slug', then enumerates the returned content (markdown, quality tier, verifier, footer). This clearly distinguishes it from sibling tools like list_skills (list vs single) and get_skill_sections (sections vs full skill).

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 a clear use case: when you have a skill slug and need the full published skill content. It does not explicitly mention alternatives or exclusions, but the 'by slug' scope and the return-content list provide enough context for an agent to choose this over listing/searching tools.

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 and idempotent behavior. The description adds valuable context beyond that: sections are 'parsed', the tool targets the 'current version', and section_index corresponds to get_skill's section_index for non-inlined sections. No contradiction; minor edge-case behaviors (e.g., empty results) are not covered.

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, all purposeful: first defines the action, second gives the usage scenario, third clarifies the optional behavior. No wasted words or repetition of schema 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?

Output schema exists, so return format is covered externally. The description sufficiently explains parameters, relationship to get_skill, and the effect of omitting section_index. It lacks only minor detail on conflicting indices (section_index vs section_indices), but overall is complete for a simple read-only tool.

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 covers 100% of parameters with descriptions, giving a baseline of 3. The description enriches this by explaining that section_index matches get_skill's index, and provides a concrete example (supplier-pattern library). This adds meaning beyond the schema's simple type/description.

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?

Description states a specific verb ('Fetch') and resource ('parsed sections of a skill's current version'), and clearly distinguishes from sibling get_skill by focusing on sections themselves. The 'not inlined' mention further defines 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?

Explicitly explains when to use: to pull a specific section listed in get_skill's section_index, and when to omit the parameter to get all sections. It references get_skill as the source of indices, giving context, though it does not explicitly name alternatives or exclusion scenarios.

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, openWorldHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds concrete output context—skill counts, accountant-verified counts, named lead verifier, and the exact code formats—which enriches the behavioral picture 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?

Three compact sentences: the first explains the output in detail, the second gives concrete query examples, and the third contrasts with a sibling tool. Every sentence earns its place with no fluff.

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, a rich output schema, and strong annotations, the description fully covers what the tool returns, when to use it, and why it is preferable to list_skills. It is complete for an agent to select and invoke this tool.

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 has zero parameters, so the baseline is 4. There is no parameter information to add, and the schema coverage is trivially complete. The description compensates by clarifying the output scope and format.

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 resource (jurisdictions with published skills) and the specific verb 'Returns' plus the detail about countries, US states, and Canadian provinces. It also differentiates itself from list_skills by saying it avoids paginating through that endpoint to compute this.

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 gives use-cases: 'Use when the user asks...' and names the alternative (list_skills) with the reasoning for choosing this tool. This is exactly the when/when-not guidance the rubric asks for.

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, openWorldHint, idempotentHint, and destructiveHint=false. The description goes beyond these by specifying that values are 'live,' includes a 'sample of topics' (warning against assuming exhaustiveness), and mentions 'defaults' are provided. This adds meaningful behavioral context without contradicting 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?

The description is a single, information-dense sentence followed by a clear action instruction. Every clause adds value—listing facets, noting liveness, and giving usage guidance—with no fluff or repetition of schema/annotation 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?

Despite the tool's simplicity, the description fully covers what it returns, when to use it, and why. The presence of an output schema means return-value details need not be in the description. It is complete for an agent to select and invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and the schema is empty, so there is nothing to explain. The baseline of 4 applies because the title's '(no args)' and the empty schema fully cover parameter semantics; the description adds no unnecessary param details.

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 tool 'returns the metadata you can filter on with search_rules' and enumerates specific facets (jurisdictions, domains, roles, block types, statuses, tax years, topics, defaults). This specific verb+resource pairing distinguishes it from sibling tools like search_rules and list_jurisdictions.

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 explicitly instructs to 'Call this before search_rules' and explains why: 'to learn the valid filter values rather than guessing.' This gives clear temporal context and an alternative (search_rules), fulfilling the 'when/when-not/alternatives' criterion.

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 readOnly/openWorld/idempotent annotations, the description discloses concrete behavioral details: pagination limits (default 100, max 200), the need for offset/next_offset for full catalogue browsing, and the recommendation to filter for performance. It also clarifies that only 'published' skills are returned, adding context not captured in annotations or 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?

The description is two dense, front-loaded sentences. The first sentence states the core purpose and result fields; the second covers filtering, pagination, and a recommendation. No filler or repetition—every clause adds value.

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 appropriately avoids detailing return values. It covers purpose, filters, pagination, dataset size, and usage recommendations, which is complete for a read-only list tool. The annotations handle safety and idempotence, so no additional caveats are needed.

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 already provides 100% coverage with descriptions for all six parameters, so the baseline is 3. The description adds operational meaning beyond the schema by explaining that filters are strongly recommended for usability, clarifying that the category field is legacy, and connecting pagination behavior to the offset parameter. This pushes it above the 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?

The description opens with a clear, specific verb+resource: 'List published OpenAccountants skills with their quality tier and verification status.' This immediately distinguishes the tool as a listing operation, and the mention of optional filters by jurisdiction, domain, and role differentiates it from sibling search tools like search_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?

The description provides clear context for when to use the tool and how to use it effectively: it explains pagination, recommends filters for the ~1,100-skill catalogue, and notes the preference for jurisdiction/domain over role. However, it does not explicitly mention when to prefer alternatives like search_skills or get_skill, so it falls short of the 'explicit alternatives' bar.

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, openWorldHint, idempotentHint, and destructiveHint false, so the safety profile is well covered. The description adds context about the nature of the data (licensed accountants, signed off on jurisdictions) and the optional jurisdiction filter, exceeding what annotations state. No contradictions.

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 purpose, followed by usage guidance and an explicit alternative. No redundant wording, every sentence contributes valuable 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?

Given the tool's simplicity, strong annotations, output schema presence, and complete parameter schema, the description fully covers purpose, usage, and constraints. The only minor omission is return format, but the output schema fills that gap, making the description 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?

The input schema has full description coverage for the single optional 'jurisdiction' parameter, so the schema already carries parameter semantics. The description does not add new parameter-level details beyond what the schema provides, making the baseline score appropriate.

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 ('Returns') and resource ('named licensed accountants... with their credentials and covered jurisdictions'), clearly distinguishing this tool from siblings like list_jurisdictions or share_with_openaccountants. It precisely communicates the tool's scope and output.

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 states when to use ('when the user asks who verified a skill or wants to see the verifier network') and provides a clear alternative for a related scenario: if the user wants a review, use share_with_openaccountants with request_review: true, at the user's explicit request. This is excellent contextual 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 indicate readOnly, openWorld, idempotent, non-destructive, and the description adds important behavioral caveats: it returns human-reviewed guidance, does not certify currentness, and may contain disagreements with official sources. This goes well beyond the structured hints.

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

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

The description is dense but every sentence adds value: purpose, sibling differentiation, examples, safety caveat, default behavior, and facet guidance. No filler or redundant restatement of the title/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?

Given the tool's complexity (12 optional params, output schema present, rich annotations), the description fully covers return shape, verification semantics, default filtering behavior, and how to discover valid facet values. The output schema covers return details, so the description does not need to enumerate them.

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 baseline is 3, but the description adds meaningful parameter context: it gives examples that illustrate text/jurisdictions/topic/tax_year usage, explains the status:'verified' shortcut, and mentions the official_source return field. It does not fully explain every parameter, but the schema already covers those details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Query individual tax RULES/FACTS' across jurisdictions, returning a bundled markdown set plus official source. It also explicitly distinguishes itself from get_skill ('Unlike get_skill ... this assembles a cross-cutting SET'), with concrete examples like 'VAT rates in MT, IE and DE'.

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 clearly contrasts with get_skill and gives concrete use cases, plus directs the agent to call list_rule_facets first to see queryable values. It also specifies when to use status:'verified' and advises confirming figures against official_source before stating them.

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, openWorldHint, idempotentHint, and destructiveHint. The description adds meaningful behavioral context, such as the distinction between 'method' and 'fact' content, and that methods carry a review_status. This goes well beyond the structured 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?

The description is logically structured, starting with the main purpose, then examples, usage condition, and content_type explanation. It is somewhat verbose with the synonym list 'Find, lookup, query, or discover,' which is redundant, but every other sentence adds value.

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 doesn't need to explain return values. It covers the key use cases (searching when slug is unknown, filtering by jurisdiction, discovering methods) and parameter semantics. It doesn't mention pagination or result limits, but given the schema richness and annotations, the description is sufficiently 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%, so the baseline is 3. The description adds value by providing concrete examples for the query parameter ('home office deduction', 'crypto capital gains') and clarifying the special behavior of content_type='method'. It does not add much for domain or jurisdiction beyond the schema, but the extra context for query and content_type justifies a 4.

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 tool's function: 'Full-text search across all published tax and accounting skills.' It provides a specific verb (search) and resource (skills), and distinguishes from siblings by noting 'Use this when you don't know the exact skill slug,' which contrasts with get_skill.

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 a clear usage condition: 'Use this when you don't know the exact skill slug.' It also explains how to discover methods via content_type. However, it does not explicitly name alternatives like get_skill or list_skills, so the 'when not to use' is only implied.

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 discloses extensive behavioral traits beyond the annotations: the paid nature of the review, that the request is saved to the user's queue, that nothing reaches an accountant until the user engages, the anonymization requirement ('no names, amounts, or PII'), and that it returns a booking link. This goes far beyond the annotation hints (readOnlyHint, openWorldHint, idempotentHint, destructiveHint).

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

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

The description is detailed but every sentence earns its place. It is logically structured: main purpose, single-channel constraint, two modes with clear markers, then constraints and invocation rules. Despite its length, it is front-loaded with the primary action and mode details, making it easy for an agent 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?

For a tool with 9 parameters, two modes, and important professional/ethical constraints, the description provides complete guidance: what the tool does, when to call it, what each mode requires, the paid nature, the user-queue behavior, and the return value (a booking link). The presence of an output schema reduces the need to explain return values in detail, but the description still covers the key outcome.

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?

While the schema covers 100% of parameters, the description adds critical semantic context: the two modes, which parameters are review-only, the conditional requirement (request_review requires working_paper + jurisdiction + scenario + contact_email), and clarifications like 'complete working paper' and 'ask for it first' for contact_email. This is a substantial contribution beyond 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 opens with a specific verb+resource: 'Sends feedback or a review request to OpenAccountants.' It also distinguishes itself as 'the single outbound channel' among the sibling tools, many of which are read/list/search operations. This clearly differentiates it from alternatives.

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?

Explicit when-to-use guidance is provided: 'does nothing unless the user has explicitly asked to send feedback or to request a review.' It further states 'Call at most once per explicit user request; never call as a routine closing step, and never solicit the request.' This gives clear exclusions and behavioral boundaries.

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 the tool read-only, idempotent, open-world, and non-destructive. The description adds useful behavioral context by specifying the two possible return types (clarification request or ready-to-execute plan) and that a missing jurisdiction triggers a clarification request. It doesn't mention the optional taxpayer_type clarification, though that is covered in the schema, so a high score is still warranted.

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

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

The description is three sentences, front-loaded with the core purpose ('Front door'), and packs in examples, required parameters, conditional behavior, and ordering. Every sentence contributes distinct information; there is no redundancy or 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?

Given the tool is an entry point into a workflow and has an output schema, the description covers all essential elements: purpose, prerequisites, behavior, and when to use an alternative. The output schema can handle the detailed plan structure, so the description does not need to explain return formats further. It is complete for its complexity.

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 value by emphasizing that 'intent' is REQUIRED and by explaining the consequence of omitting jurisdiction (returns a clarification request). It also clarifies the purpose of 'acting_as' indirectly via 'Never guess' in the schema, but that is schema rather than description. Overall, the description adds meaningful parameter context without duplicating 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 clearly identifies the tool as the 'front door' for any tax/accounting question and explicitly says to call it FIRST whenever the user asks for tax help. It distinguishes itself from the sibling 'start_help' by stating that start_help should be used only when an intent is not yet known.

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 provides explicit when-to-use guidance: 'Call this FIRST (after start_help if needed) whenever the user asks for tax help.' It also names the alternative (start_help) and the condition for using it: 'If you don't yet have an intent, call start_help first.' This is clear and actionable.

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, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context: that the response is conditional on the user's status (approved accountant vs. others) and what each type of user receives, plus the recommended next step. This goes beyond the annotations without contradicting them.

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

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

The description is a single dense sentence but is front-loaded with the essential role ('No-argument front door') and immediately provides actionable usage instructions. While it is somewhat long, every clause carries meaningful information and there is no redundancy. It could be split into two sentences for readability, but it remains appropriately sized for the content.

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 that the tool has no parameters and an output schema is present (which presumably describes the return structure), the description covers the key contextual aspects: what the tool does, when to use it, what it returns for two user categories, and the follow-up action. It also clearly differentiates from siblings, making it complete for an AI agent to select and invoke 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?

The tool has zero parameters, and the description explicitly notes 'no-argument' and 'No-argument front door,' which is sufficient. With no schema properties to explain, the baseline of 4 is appropriate; the description adds no unnecessary parameter details.

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 identifies this as a no-argument front door for scoping user requests, with a specific verb ('call this FIRST'), a resource (tax-workflow guidance), and distinct behavior for signed-in approved accountants versus everyone else. It explicitly distinguishes itself from sibling tools like list_jurisdictions and start, making its purpose unambiguous.

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 provides explicit when-to-use guidance ('call this FIRST whenever a user asks...') and when-not-to-use guidance ('do NOT answer such questions by listing your tools or calling list_jurisdictions'). It also names the follow-up tool (`start(intent, jurisdiction)`) and the condition for using it, which fully covers usage context.

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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description adds crucial behavioral context: it is a live external lookup, may be temporarily unavailable and will say so plainly rather than inventing an answer, and covers only EU/XI jurisdictions. This gives the agent realistic expectations about failure modes and scope.

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

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

The description is appropriately sized given the tool's complexity, with every sentence conveying necessary information. It is front-loaded with a clear purpose, then covers usage, coverage, and failure behavior efficiently without redundancy.

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 description covers purpose, usage scenarios, geographical coverage and limitations, behavior on unavailability, and the nature of the output (business name/address). With an output schema present and rich annotations, this description provides all context an agent needs to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already describes both parameters with 100% coverage. The description adds further meaning by explaining accepted input formats (with/without country prefix, with/without spaces) and clarifying the 'EL' for Greece and 'XI' for Northern Ireland special cases, going well beyond 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 clearly states the tool checks whether a VAT/tax number is real and registered via a live government registry, and returns the registered business name and address when disclosed. This specific verb+resource phrasing distinguishes it from sibling tools like search_rules or list_jurisdictions, which serve different purposes.

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 explicitly states when to use the tool ('whenever a user wants to verify a supplier's or customer's tax ID' before reverse charge, zero-rating, or vendor onboarding) and when not to use it (non-EU numbers, telling the user to avoid guessing). It also contrasts with 'knowledge lookup or training data', giving clear usage guidance vs alternatives.

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