Irish Tax Hub

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

Annotations already declare the safety profile (readOnlyHint=true, no destruction, closed world), so the bar is lower and the description does not contradict them. It adds useful behavioral context about what each calculator computes and notes that the full result is returned, but says nothing about validation failures, unsupported year ranges, or partial-result behavior for the more complex calculators.

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

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

Front-loaded with purpose, then the calculator list and examples, which are load-bearing for a 20-way dispatcher. It is long and the examples are numerous, but each line earns its place by disambiguating a calculator; a tighter grouping of examples would be the only improvement.

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

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

With an output schema present, return-value documentation is not needed, and the description fully covers the dispatch contract, enum-to-meaning mapping, and input examples. For a polymorphic tool over a free-form object, nothing an agent needs to select and call it correctly is missing.

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

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

Schema coverage is 100% and both parameters are named in the schema, yet the description goes well beyond it: the raw enum values ('sarp', 'vat3', 'cat', 'refund-for-move-date') would be opaque without the accompanying descriptions, and the 11 example payloads show concrete field shapes for the nested `inputs` object that the schema leaves as free-form additionalProperties.

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?

Opens with a specific verb+resource ('Run an Irish tax calculator and return the full result') and then enumerates all 20 supported calculators with a one-line scope for each, so the agent can map a user need to a calculator without opening the schema. It is clearly distinguished from informational siblings like list_calculators and get_calculator_schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states the invocation contract ('Pass the calculator name and its required inputs') and routes to the alternative in the exact condition where it is needed ('Use `get_calculator_schema` first if you need to know the exact input fields'). The per-calculator examples make the when-to-use decision concrete rather than inferable.

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 openWorldHint=false, so the safety profile is covered. The description adds that the tool is a discovery step preceding calculate_tax, which is useful sequencing context, but discloses nothing about auth, rate limits, or failure modes. With annotations carrying the burden, a 3 is appropriate.

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 short sentences, each earning its place: what it returns, what the payload contains, and when to call it. The usage directive is front-loaded enough to be read first.

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-value documentation is not strictly required, yet the description still summarizes the payload (fields, types, defaults, constraints). Combined with the sequencing guidance versus calculate_tax, the definition is complete for straightforward invocation.

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

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

Schema coverage is 100% with a single enum parameter whose description ('The calculator to get the schema for') and 20 allowed values are fully documented in the schema. The description adds no syntax or selection guidance beyond 'specific tax calculator', so the baseline 3 applies.

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

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

The description states a specific verb and resource ('Get the JSON Schema for a specific tax calculator') and clarifies scope with 'specific', which distinguishes it from the sibling list_calculators. It also ties itself to calculate_tax, though the differentiation from the listing tool is left implicit rather than stated.

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 before calling `calculate_tax` if you need to know what fields are required.' That names the sibling and the triggering condition. It does not state when NOT to use it (e.g., when field requirements are already known).

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 openWorldHint=false, so the safety profile is covered without the description's help. The description adds only that the subject is 'usage statistics' rather than configuration or schema, which is modest value 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?

A single short sentence with no padding, and the key noun ('usage statistics') is front-loaded. It is efficient, though arguably too terse to earn a top 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?

With an output schema present, the description need not explain return values, and the one parameter is fully documented in the schema. The remaining gap is routing: nothing tells the agent why to call this instead of the sibling tools that also operate on a named calculator.

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

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

Schema description coverage is 100% and the single parameter carries both a description and a full enum of calculator names, so the schema does the heavy lifting. The description adds no format, default, or naming guidance beyond it, making the baseline 3 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?

States a specific verb ('Get') and resource ('usage statistics') scoped to 'a specific tax calculator', which is more precise than the title. However, it does not differentiate itself from siblings such as get_calculator_schema or list_calculators, which also concern individual calculators.

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?

There is no indication of when to reach for this tool versus list_calculators (which enumerates calculators) or get_calculator_schema (which describes their inputs). No prerequisites, no exclusions, no alternative routing is given.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the nature of the returned data (filing and payment deadlines), but says nothing about coverage, ordering, or whether a year with no data returns empty versus an error.

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?

A single front-loaded sentence that states the resource and its contents with zero filler. Nothing is redundant with the name and nothing extraneous is included.

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 and annotations cover the safety profile, so return values need not be described. The description is adequate for a simple read-only lookup, though it leaves the interaction between the optional filters unexplained.

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

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

Schema description coverage is 100%, so all three optional filters (year, month, tax_type) are documented in the schema with examples and the current-year default. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb (Get) and resource (Irish Revenue dates and deadlines) and enumerates the content types (filing dates, payment dates). It does not need to differentiate from siblings, since none of the other tools deal with dates, but it also never references any of them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied rather than stated: an agent can infer this is the lookup tool for deadline questions, and no sibling overlaps with it. There is no explicit when-to-use framing, no mention of how to combine the year/month/tax_type filters, and no exclusions.

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 establish a safe, non-destructive, closed-domain read. The description adds genuinely new behavioral context: 'Not all documents have extracted text available' (a partial-failure caveat an agent must anticipate) and the attribution/licence obligation when reusing content. It stops short of saying whether absent text yields an error or an empty result.

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

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

Front-loaded with purpose, then the workflow, then the caveat, then licensing. Slightly padded by the licensing paragraph and stray double-backtick artifacts (``url``), but each section carries actionable information for a retrieval tool whose output must be cited.

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-value shape needn't be restated. The description covers the key gaps an agent needs — the search-first workflow, accepted input forms, possible missing text, and attribution requirements. Only the failure mode when text is unavailable is left unstated.

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

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

Schema coverage is 100% and the property description already enumerates the accepted input forms, so the schema does the heavy lifting. The description's mention that URLs, paths and bare filenames are accepted and that the search result's url can be passed directly reinforces the linkage to the search tool, but adds little beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Get the full text of a specific Revenue Tax & Duty Manual document'), and distinguishes itself from the sibling search tool that only finds documents. An agent can tell exactly what this returns 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?

Explicitly prescribes the workflow: 'Use search_revenue_documents first to find the document' and explains that the search result's url can be passed straight through. This is a clear prerequisite plus the alternative to use upstream, leaving nothing to inference.

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

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

Annotations already cover the safety profile (read-only, non-destructive, not open-world), and the description adds genuinely useful context beyond that: the content provenance (public sector, revenue.ie) and a concrete attribution obligation when citing results. It does not discuss freshness or volume of the changelog, but the licensing/citation guidance is real added value.

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

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

Front-loaded with the purpose in the first sentence, then usage, then licensing. The licensing sentence is long and somewhat detailed for a tool description, but it carries actionable operational instructions rather than filler.

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

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

For a parameterless read-only tool with an output schema, the description covers what it returns, when it is useful, and how to handle the results' attribution. Nothing needed to call it correctly is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies.

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

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

States a specific verb and resource ('Get the Revenue eBrief changelog') and clarifies the resource as 'recent updates to Revenue guidance and Tax & Duty Manuals', which separates it from document-retrieval siblings like get_revenue_document_text. It does not explicitly name an alternative, but the scope is 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?

'Useful for checking what Revenue guidance has changed recently' gives an implied usage context but no when-not-to-use guidance and no reference to alternatives such as search_revenue_documents or get_revenue_document_text. Adequate but leaves routing to inference.

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 openWorldHint=false, covering the safety profile. The description adds a usage nuance ('without running a full calculation') but no further behavioral details such as caching, error behavior, or versioning. With the annotation burden lifted, a 3 is appropriate.

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 short sentences, front-loaded with the core action, then returns, then usage context. No redundant or wasted phrasing.

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

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

For a simple read-only constants getter with a fully documented input schema, output schema, and clear annotations, the description is sufficiently complete. It states purpose, returned data, and when it is useful.

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 single optional year parameter is fully documented in the schema. The description adds no additional meaning about the parameter, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get Irish tax constants') and enumerates the returned categories, which helps distinguish it from calculation tools. The phrase 'without running a full calculation' sets it apart from the sibling calculate_tax without needing 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?

Provides clear context ('understanding the current tax rules without running a full calculation') that implies when to use this instead of a calculator. However, it does not name the alternative sibling (calculate_tax) explicitly or state exclusions, so it falls short of full when/when-not guidance.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), so the description's added value is the failure-mode caveat 'Not all documents have extracted text available' plus the licensing/attribution requirement for citing results. These are genuine behavioral traits beyond the structured fields, though rate limits and truncation behavior are not addressed.

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 core action and the search-first prerequisite are front-loaded in the first two sentences, followed by the accepted input forms and the caveat. Every sentence carries distinct information with no padding.

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

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

With an output schema present, return values need not be explained. The description still covers the workflow prerequisite, the accepted identifier forms, the possibility of missing extracted text, and citation attribution — everything needed to invoke and use the result correctly.

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

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

Schema description coverage is 100% and the property description already enumerates bare filename, .pdf filename, full URL, and textUrl value. The description restates the same accepted forms without adding syntax or format detail, so it is baseline-adequate rather than additive.

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

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

States a specific verb and resource ('Get the full text of a specific tax-treaty document') and scopes it to a single named document. This clearly separates it from siblings like get_revenue_document_text and search_tax_treaties without needing to open any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly names the prerequisite and the alternative: 'Use search_tax_treaties first to find the document.' That routes the agent correctly. It stops short of a when-not-to-use this tool (e.g. when to prefer get_revenue_document_text instead), so it is clear but not fully exhaustive.

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 openWorldHint=false, so the safety profile is covered. The description adds that results feed into `calculate_tax`, which is genuinely useful workflow context, but says nothing about ordering, stability, or caching behavior beyond what the output schema already conveys.

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

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

Two short sentences, front-loaded with the primary action and scope. The second sentence partially restates the first ('returns a list of calculators') while adding the `calculate_tax` link, so it earns most but not all of its space.

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

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

With an output schema present, the description need not describe return values, and zero parameters remove input burden, so it is largely complete. The only mild gap is that it does not say whether the list is exhaustive or how it relates to the other calculator-adjacent siblings.

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 per the rubric the baseline is 4. The description does not need to explain any inputs and correctly avoids doing so.

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 gives a specific verb+resource (list all available Irish tax calculators) and states what is returned (names and descriptions). It links to the sibling `calculate_tax` tool, clarifying its place in the workflow, though it does not differentiate itself from other list-style siblings such as `list_tax_treaty_countries`.

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 phrase 'that can be used with the `calculate_tax` tool' implies this is a discovery step preceding calculation, which is useful implied usage. However, there is no explicit when-to-use guidance, no statement of when a caller should prefer `get_calculator_schema` or `get_calculator_stats` instead, and no exclusions.

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 openWorldHint=false, so the safety profile is covered. The description adds a behavioral obligation beyond that: reproduce the source's attribution (or attribution.source.statement) when citing, which is useful context the annotations do not convey.

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

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

Three sentences, front-loaded with the purpose and the usage pairing, then the attribution note. The attribution sentence is longer than strictly necessary but carries required licensing detail, so the structure is efficient overall.

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 parameterless listing tool with an output schema and complete annotations, the description covers purpose, usage pairing, and citation requirements. Return values are handled by the output schema, so nothing essential to invocation is missing.

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

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

The tool takes zero parameters, so the baseline is 4. There are no parameters whose semantics the description would need to explain, and it correctly adds no redundant parameter text.

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

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

The description states a specific verb and resource: listing all available categories for Revenue Tax & Duty Manual documents. It is clearly distinguishable from most siblings (get_*, calculate_*, search_*) by naming the exact resource domain. It stops short of an explicit contrast with the other list_* tools, so a 4 rather than a 5.

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 a clear use context: pair this with search_revenue_documents to filter results by category. That is actionable guidance on when the tool is relevant. It does not state when-not-to-use or name alternative filtering paths, so it falls short of the explicit alternative-selection that would earn 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 readOnly=true, openWorld=false, destructive=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: the data is reused from public-sector sources, carries a CC BY 4.0 licence, and must be attributed using the result's own attribution or attribution.source.statement. No return-shape detail, but an output schema exists.

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

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

Front-loaded with the one-line purpose, then the sibling relationship, then the licensing note. The attribution sentence is dense but does real work; overall there is no filler, though the licence text could be tightened.

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 documenting the return shape, zero parameters, and annotations covering safety, the description supplies everything else an agent needs: what it lists, how it pairs with search_tax_treaties, and the mandatory attribution requirement.

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 there is no parameter semantics for the description to add. Baseline for 0 params applies.

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

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

States a specific verb and resource with scope: 'List all countries with an Irish double-taxation treaty.' It also distinguishes itself from the sibling search_tax_treaties, which is named explicitly as the filtering counterpart.

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?

'Use with `search_tax_treaties` to filter results by country' tells the agent how this tool pairs with the sibling, implying this one enumerates and the other narrows. It stops short of an explicit when-to-use/when-not-to-use statement, but the routing intent is clear.

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, openWorldHint=false, so the safety profile is covered without description help. The description adds genuinely non-structured context about result reuse, the PSI/CC BY 4.0 licence, and where to source attribution when citing, but it says nothing about rate limits, result ordering, or pagination 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?

Front-loaded with the purpose, then return values, then the sibling hand-off, so the operative content comes first. The trailing licence/attribution paragraph is longer than the rest and slightly dilutes focus, though it carries compliance information an agent may need.

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

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

With an output schema present, the description need not enumerate return values, yet it does so briefly, and it covers the query payload, the category-filter escape hatch, and the follow-up tool for full text. The remaining gap is search-behavior detail (matching, ranking, pagination), which is minor for a keyword-search 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 description coverage is 100%, so query, limit, and category are already fully documented including examples, default, and bounds. The description adds no syntax, formatting, or matching-behavior detail (e.g., phrase vs. boolean semantics) beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Search Irish Revenue Tax & Duty Manual (TDM) documents') and immediately names what it returns (titles, categories, filenames). It is clearly distinguished from the sibling get_revenue_document_text, which it identifies as the full-text reader.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent: use this tool for keyword discovery, then use `get_revenue_document_text` to read full text, and the schema points to `list_revenue_document_categories` for filter values. It gives clear context and a named alternative but no explicit when-not guidance (e.g., how it differs from search_tax_treaties).

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 establish readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuine behavioral context beyond that: the returned fields, and an explicit licensing/attribution obligation (PSI/CC BY 4.0, use attribution.source.statement when citing). It does not discuss result-count or pagination behaviour beyond the limit parameter, which keeps it short of a 5.

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

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

Front-loaded with what the tool does, followed by the sibling routing, then licensing. Every sentence earns its place, though the licensing sentence is somewhat long and the trailing attribution clause is dense enough to slow parsing slightly.

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

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

An output schema exists, so the description need not enumerate return values, and annotations cover the safety profile. The one omission a careful agent might want is any hint about how results are ordered or whether the search is exact-phrase or keyword-AND, but for a simple filtered search this is close to 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 coverage is 100%, so limit, query and country are already documented in the schema, including example query strings and the pointer to list_tax_treaty_countries. The description only restates the keyword/country combination without adding format, matching, or syntax detail, so the baseline 3 applies.

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

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

States a specific verb (search) and resource (Ireland's double-taxation treaty documents), enumerates what the corpus contains (treaties, protocols, MLI texts), and summarizes the returned fields. It is clearly distinguishable from get_tax_treaty_text, which it explicitly routes the agent to for full text.

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?

Specifies how to find documents ('by keyword and/or country') and names the alternative tool plus the condition that selects it: use get_tax_treaty_text to read the full text rather than searching again. The 'and/or' phrasing also clarifies that query and country can be combined independently.

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