OpenAccountants

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses numerous behavioral traits: it is deterministic, returns a per-criterion threshold table and canonical citations, surfaces a live verification envelope, and treats 'cannot_determine' as a first-class outcome. It also clarifies the behavior when prior-year data is absent and the implications of group_member forcing 'review'. No contradictions 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 information-dense; every sentence carries essential guidance (coverage, behavior, edge cases). It front-loads the core purpose and determination values first. It could be trimmed slightly without losing key warnings, but given the tool's complexity, the length is justified.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with multiple jurisdictions, a two-year test, and a verification envelope, the description covers all critical aspects: input requirements, conversion rules, correct handling of missing data, and the meaning of 'cannot_determine'. With an output schema also provided, an agent has everything needed to call and interpret 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?

Even though the schema already describes every parameter (100% coverage), the description adds critical semantics: currency must match the regime and must be converted first (never guessed), prior year is needed for the consecutive-years test and its absence changes the result, and group_member forces 'review'. These enrich the schema meaning substantially.

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 'DETERMINISTIC check of whether a private limited company qualifies for statutory audit exemption' — a specific verb, resource, and outcome. It explicitly names the determination values ('exempt' | 'review' | 'audit_required' | 'cannot_determine') and lists the inputs, making its scope unmistakable and distinct from the audit/deadline/search siblings.

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 strong usage guidance: it states the covered jurisdictions (MT, GB) and eras, instructs to pass prior_year figures for two-consecutive-years tests, and explains why a missing prior year correctly returns 'review' not 'exempt'. It also warns against overriding with training-data thresholds. It does not explicitly name alternative tools for uncovered scenarios, so it slightly misses the 'when-not' comparison.

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, so the safety profile is covered. The description adds valuable behavioral context: it specifies the data source (OpenAccountants tax calendar) and that the response marks jurisdiction_source, which helps the agent interpret results. It doesn't describe output format, but the presence of an output schema mitigates that gap.

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

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

The description is moderately long but every sentence adds value: it states purpose, usage triggers, and a nuanced parameter behavior. It is front-loaded with the primary purpose and avoids redundancy. Slightly longer than strictly necessary, but no waste.

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 has an output schema, the description covers all essential aspects: what it returns, when to use it, and how to handle optional parameters. The agent has everything needed to invoke it correctly without additional inference. No significant gaps remain.

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 details like default and max for horizon_days, and acceptable formats for jurisdiction. The description enhances this by clarifying the optional jurisdiction behavior for signed-in users, which is not fully captured in the schema. This adds value beyond the schema, justifying a 4 over the baseline 3.

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 ('get') and resource ('deadlines') and clearly defines the scope: 'Upcoming filing/payment deadlines and recurring filing rhythms ... for a country or US state.' This unambiguously separates it from siblings 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 gives explicit triggers: '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 explains the optional jurisdiction behavior for signed-in users, leaving no ambiguity about when to call and how to handle the optional parameter.

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, and destructiveHint=false, so the safety profile is covered. The description adds valuable context about what the response includes (markdown, quality tier, verifier conditionally, provenance footer), going beyond the annotations to describe the data payload. There is 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 entire description is a single, information-dense sentence that front-loads the core action ('Fetch a published skill by slug') and then lists the key return elements. There is no wasted language, and the structure is logical and efficient.

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 fetch operation, the description covers all essential aspects: what resource is accessed, how it is identified, and what the caller can expect to receive. An output schema exists, so return structure is already defined externally, and the description's mention of content types is sufficient. No critical missing information for an agent to call this correctly.

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

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

Schema description coverage is 100%, and both parameters (slug and reason) are documented in the schema. The description merely references 'by slug' which aligns with the schema but adds no extra semantic detail beyond it. The schema already provides an example for slug and a rationale for reason, so the description offers no incremental parameter guidance.

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 starts with a specific verb 'Fetch' and a resource 'published skill by slug', then enumerates the exact content returned (markdown, quality tier, verifier, provenance footer). This clearly distinguishes the tool from siblings like list_skills and search_skills, which list or search across multiple 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 implies the use case: fetching a specific skill by its slug. It makes clear that this is for retrieving a single published skill, which differentiates it from broader list/search tools. However, it does not explicitly mention when to avoid this tool or call a sibling instead, so no exclusion or alternative is named.

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, so the safety profile is covered. The description adds useful behavior: it returns 'parsed sections' with 'heading and markdown content', and clarifies the 'current version' constraint. It also explains how parameter omission affects the result (all vs. one). This goes beyond 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?

Two sentences with zero fluff, front-loaded with the core purpose and followed by usage guidance. Every clause earns its place, and the structure makes it easy to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the return format is already defined. The description covers the main input behaviors (single vs. all sections) and the relationship to get_skill. It does not mention edge cases like invalid indices or empty results, but for a read-only, idempotent tool with clear parameter semantics, this is sufficient. Slightly more detail on `section_indices` could push it to 5.

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 each parameter is documented. The description enhances this by explaining the relationship between `section_index` and get_skill's `section_index`, and explicitly states that omitting it fetches all sections. This adds semantic value beyond the schema's bare descriptions, particularly for the `section_index` parameter.

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 verb ('Fetch') and resource ('parsed sections of a skill's current version'), and distinguishes it from get_skill by referencing the `section_index` that get_skill provides. An agent can immediately tell this tool retrieves section content, not metadata.

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 it (to pull a specific section that get_skill listed as not inlined) and how to control the output (pass `section_index` or omit it). It references the sibling tool get_skill indirectly but doesn't explicitly contrast it for other scenarios (e.g., 'use get_skill for metadata'), so not a full 5.

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 is read-only, idempotent, and non-destructive. The description adds useful context about the exact data returned (skill counts, accountant-verified counts, named lead verifier) and implies no pagination. This goes beyond the annotations and the empty schema, so it earns a solid score.

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 sentences, front-loaded with the core purpose and return content, followed by usage examples and a comparison to a sibling. Every sentence earns its place with no filler, making it highly concise and well-structured.

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-parameter list tool with an output schema, the description explains what data the tool returns (including specific counts and verifier names), provides trigger examples, and notes the alternative. Nothing essential is missing; the output schema covers the return format, so the description is 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 tool has zero parameters, so the schema fully defines that there are no inputs. The description adds no parameter details because none are needed. Per the calibration rule for 0 params, the baseline is 4, and the description meets it without extraneous information.

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'), a clear resource ('every jurisdiction with published skills'), and detailed content (countries, US states, Canadian provinces, with counts and verifier). It also explicitly distinguishes itself from a sibling tool ('Avoids paginating through list_skills to compute this'), 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 example queries that trigger this tool ('which countries does OpenAccountants cover?' or 'what's available for [country]?'), and it references a sibling alternative (list_skills) that it avoids. It does not enumerate exclusions for other sibling tools, but the examples and the alternative mention give solid practical 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, and destructiveHint=false; the description adds that the data is 'live' and includes defaults, implying dynamic availability over static metadata. This enriches behavioral context without contradicting 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?

Two efficiently structured sentences front-load the purpose, enumerate the facet types, and conclude with a concrete usage tip. No redundant or filler content exists.

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 no-argument read-only tool with an output schema and safety annotations, the description provides everything an agent needs: what the tool returns, why it is useful (learn valid filters), and that defaults are included. Nothing is missing for correct invocation.

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

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

The tool takes zero parameters, so no parameter details are needed. The schema coverage is trivially 100% with an empty object, and the baseline of 4 applies when there are no parameters to explain.

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 filterable metadata for search_rules, enumerating specific facet types (jurisdictions, domains, roles, block types, statuses, tax years, topics) and defaults. This verb+resource specificity distinguishes it from sibling list tools by tying it directly to the search_rules workflow.

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 instructs to call this before search_rules to learn valid filter values, preventing guessing. It gives a clear when-to-use directive but does not name alternative tools or describe when not to use it, so it falls short of the full 5.

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 carry the safety profile (readOnlyHint, idempotentHint, non-destructive, closed world), so the description's burden is lower. It adds genuinely useful behavioral context beyond the annotations: pagination cap of 200, the offset/next_offset paging contract, and the catalogue scale (~1,100 skills) that motivates filtering. 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?

Core purpose is front-loaded in the first sentence, followed by filters and pagination. Every sentence earns its place — filter examples, role enumeration, pagination limits, and a recommendation. It runs slightly long for a single block, but there is no repetition 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?

An output schema exists (so return values are documented), annotations cover the safety profile, and the description handles filter options, paging mechanics, and catalogue size. The only notable gap is not explicitly routing agents to search_skills for targeted lookups, but for a filterable list tool the coverage is otherwise strong.

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 every parameter already has a description, so the baseline is 3. The description adds marginal value by giving concrete example values ('US', 'MT', 'DE', 'GB'; 'vat-gst', 'payroll') and explaining the offset/next_offset paging link that the schema only hints at. The schema still carries the heavy lifting; the description enriches rather than compensates.

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 ('List') and resource ('published OpenAccountants skills') and names the payload ('quality tier and verification status'). The list-vs-search distinction vs. the search_skills sibling is implicit but clear, and the qualifier 'published' adds precision. An agent can tell this from get_skill or search_skills without opening the 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 concrete, actionable guidance: filter by jurisdiction/domain/role, notes the default/max pagination bounds, and explicitly recommends filters because the ~1,100-skill catalogue 'requires paging via offset/next_offset'. This is clear context on how to call effectively. It lacks explicit exclusions or a when-not-to-use pointer toward search_skills, which keeps it from a 5.

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, destructiveHint=false, and idempotentHint=true, so the description does not need to restate those. It adds useful context about the return content (licensed accountants, credentials, covered jurisdictions) and notes the explicit user-request requirement for the alternative path. This is adequate beyond the annotations, though it doesn't mention rate limits or pagination, which is minor given the simplicity.

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 sentences, front-loaded with the core purpose, followed by usage context and an explicit alternative. Every word contributes value—no filler or repetition of what annotations already provide. It is efficiently structured for quick agent parsing.

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 simple read-only tool with one optional parameter and an output schema present, the description fully covers when to use it, what it returns, and how it relates to sibling tools. Nothing essential is missing; the output schema handles return structure, and the description provides the necessary decision context.

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 description for the jurisdiction parameter is complete (100% coverage), so the parameter is already well-documented. The description adds no additional meaning beyond 'for this jurisdiction,' which aligns with the schema. Baseline 3 is appropriate because the schema carries the semantic weight and the description does not contradict or enhance 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?

The description clearly states a specific verb ('Returns') and resource ('named licensed accountants who have signed off on OpenAccountants jurisdictions') along with the data included (credentials, covered jurisdictions). It distinguishes itself from siblings by explicitly naming the review flow via share_with_openaccountants, making its scope 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?

It provides explicit when-to-use guidance ('Use when the user asks who verified a skill or wants to see the verifier network') and also gives a when-not-to-use condition, routing review requests to share_with_openaccountants with request_review: true. This directly addresses alternatives and exclusions, leaving no ambiguity for the agent.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds genuinely valuable behavioral caveats beyond those: entries may be GUIDANCE rather than figures ('never read one as a figure'), and the tool 'does NOT certify that a figure is current' — with the instruction to confirm against official_source and prefer it on disagreement. This level of behavioral nuance is exactly what annotations cannot convey.

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

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

Long but every sentence earns its place for a 12-parameter cross-jurisdiction tool. The core purpose is front-loaded, emphasis is used sparingly and effectively (ACROSS, OFFICIAL SOURCE, GUIDANCE, IMPORTANT), and the structure flows from purpose → routing → caveats → defaults → prerequisites. Justified length given the tool's complexity, though tighter than a 5 would require.

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 complex cross-jurisdiction tool with 12 params, full schema coverage, and an output schema (so return values need not be spelled out), the description covers all key decision points: return shape (markdown set + official_source), routing to search_skills/get_skill, the guidance-vs-figure trap, currency caveat, status filter, and the list_rule_facets prerequisite. Very complete; only minor gaps like pagination behavior (offset/next_offset) are left to the schema.

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

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

Schema description coverage is 100%, so the schema already documents all 12 parameters, warranting the baseline of 3. The description does add some value: it clarifies the status:'verified' shorthand as selecting accountant-/research-verified only, and points to list_rule_facets for queryable facet values (domains, etc.). But it doesn't materially enrich what the schema already states for most parameters.

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 opens with a specific verb+resource: 'Sweep tax rules ACROSS jurisdictions and metadata and get back a bundled markdown rule set plus the jurisdiction's OFFICIAL SOURCE.' It names the cross-cutting use case with concrete examples ('VAT rates in MT, IE and DE') and explicitly differentiates from the sibling search_skills/get_skill pair. An agent can tell exactly what this tool does and what it is not for.

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 ('Best for cross-cutting questions'), explicit when-not-to-use with the named alternative ('WHEN YOU WANT ONE SPECIFIC FIGURE... prefer `search_skills` then `get_skill`'), including the rationale (a figure can exist in the Guide without existing as a separate rule). Also prescribes a prerequisite ('Call `list_rule_facets` first'). Routing guidance is unambiguous and complete.

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, and non-destructive hints, so the baseline is lower. The description adds valuable behavioral context: it clarifies that methods are executed via start(), that each method carries a review_status (accountant-reviewed | source-cited), and that results may include either or both content types. This enriches understanding 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?

The description is relatively long but well-structured: it opens with the core purpose, provides examples, then covers usage guidance and content_type semantics. Every sentence adds operational value (examples, when-to-use, method vs fact distinction). It is not overly terse nor redundant, though a slightly tighter phrasing could reduce length without loss.

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 4-parameter tool with an output schema, the description covers all essential aspects: what it searches, when to use it, how to use content_type, jurisdiction limiting, and the review_status attribute. It doesn't describe pagination or result formatting, but the output schema presumably covers that, so the description need not. It is complete relative to its complexity and sibling context.

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. The description adds meaning beyond the schema: it explains the query parameter with concrete examples and advises that 'With content_type='method', a broad term lists the available methods.' It also clarifies the distinction between 'method' and 'fact' in the content_type parameter, which the schema only labels as 'What kind of Guide to find.' This additional context aids correct usage.

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

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

The description clearly states the action (full-text search) and the resource (published tax and accounting skills). It provides concrete examples ('home office deduction', 'Schedule C') and explicitly differentiates from siblings by saying 'Use this when you don't know the exact skill slug' – distinguishing it from get_skill and list_skills, which require known slugs or full lists.

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 when-to-use guidance: 'Use this when you don't know the exact skill slug.' It also explains the content_type parameter ('method' for executable procedures vs 'fact' for reference material) and how to leverage it for discovery. This is clear and actionable, covering both the core and edge use cases.

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, but the description adds crucial behavioral context: the anonymization requirement ('no names, amounts, or PII'), the fact that reviews are a paid engagement ('never describe it as free'), the queuing behavior ('nothing reaches an accountant until the user engages'), and the one-call limit. This far exceeds what annotations convey and provides actionable behavioral rules.

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 earns its place. It front-loads the core purpose and the single-channel constraint, then structures two modes with clear prerequisites. The caveats (anonymization, paid engagement, manual queue, call limits) are packed efficiently without fluff. For a tool with 9 parameters and two complex modes, this is remarkably concise.

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—two modes, conditional parameters, potential legal/ethical implications—the description covers all necessary aspects: what triggers it, how each mode works, required parameters, behavioral constraints, and even notes about the output (booking link). The output schema exists, so return format is covered, and the description is sufficient for correct invocation without relying on external knowledge.

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 schema coverage is 100%, the description adds significant semantic value by explaining the interaction between parameters: how request_review toggles the mode, the conditional requirement for contact_email, the completeness expectation for working_paper, and the anonymization constraint on note. It also clarifies that skill_slug is for skill-specific feedback and replaces old submit_feedback. This goes well beyond the schema's per-parameter descriptions.

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 clear verb and resource: 'Sends feedback or a review request to OpenAccountants.' It also explicitly declares itself 'the single outbound channel,' distinguishing it from the read-only sibling tools. The two modes are clearly outlined, leaving no ambiguity about what the tool does.

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 when-not-to-use guidance: 'does nothing unless the user has explicitly asked,' 'Call at most once per explicit user request; never call as a routine closing step, and never solicit the request.' It also specifies the conditions for each mode, such as requiring working_paper, jurisdiction, scenario, and contact_email for request_review. This is comprehensive 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context beyond that: it explains the return behavior (clarification request or plan) and notes that the 'reason' parameter is 'captured only to improve routing', which is transparent about its side-effect-free intent. It doesn't describe error conditions or rate limits, but the annotations plus this additional info are sufficient for an agent to understand the tool's 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?

The description is dense but every sentence earns its place. It front-loads the purpose and usage, then covers parameters efficiently without redundancy. The structure flows logically from general to specific, and the inclusion of usage examples (e.g., 'MT', 'GB', 'US-CA') adds value without bloat. It is concise given the complexity of the tool.

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 5-parameter tool with an output schema, this description is remarkably complete. It covers all parameter semantics, provides clear usage flow, and explains the return types (clarification or plan). It also addresses edge cases like missing jurisdiction and unsure taxpayer_type. The description gives an agent everything needed to decide when and how to call this tool correctly, making it fully self-contained.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by providing additional meaning: it marks 'intent' as REQUIRED, explains 'acting_as' in detail with concrete examples and a directive to never guess, and elaborates on 'taxpayer_type' including when it is needed and when to omit it. These enrich the schema beyond simple field definitions, justifying a score above 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 a clear purpose: it is the 'front door' for tax/accounting questions, and it explicitly differentiates itself from the sibling start_help. It names the resource (workflow) and the action (start), and the scope is well-defined (any tax/accounting question). An agent can immediately tell this is the entry-point tool.

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 usage guidance: 'Call this FIRST (after start_help if needed) whenever the user asks for tax help.' It also specifies when not to use it ('If you don't yet have an intent, call start_help first') and names the alternative start_help. It even instructs how to handle missing jurisdiction or unclear actor, making the decision path unambiguous.

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, idempotent, and non-destructive behavior. The description adds meaningful behavioral context beyond that: it branches based on whether the user is a signed-in approved accountant, and it describes the two distinct return shapes. It also conveys that this is an entry point rather than a data-fetching endpoint, which is useful for the agent's expectations.

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 compact but information-dense, with the core instruction front-loaded. Every clause earns its place: when to call, what not to do, what it returns for each audience, and what to call next. No filler or repetition of 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?

For a zero-argument tool with an output schema, the description covers everything the agent needs: the triggering conditions, the two possible response types, and the follow-up action. The routing to `start` ties this tool into the broader workflow, making it complete in context.

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 and the schema coverage is 100%, so there is nothing for the description to add about parameters. The baseline for zero-parameter tools is 4, and the description correctly emphasizes that it takes no arguments ('No-argument front door').

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 purpose: a no-argument front door that returns orientation or scoping questions. It distinguishes itself from siblings by naming `list_jurisdictions` as something not to call and `start` as the follow-up. The verb 'call this FIRST' makes the tool's role 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 gives explicit when-to-use guidance with example user phrasings, and equally explicit when-not-to-use guidance ('do NOT answer such questions by listing your tools or calling list_jurisdictions'). It also tells the agent exactly what to do next: 'Once you have an intent, call `start(intent, jurisdiction)`.' This leaves no ambiguity about 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?

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.