Akay trade offers (akay.ie)

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds only that the returned details are 'public' and that the id must originate from a prior search; it says nothing about missing-id behavior, auth, or rate limits.

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

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

One front-loaded sentence that states verb, resource and the id's provenance with no filler. It is appropriately sized for a one-parameter lookup, though it spends its only clause on provenance rather than sibling disambiguation.

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

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

An output schema exists, so return values need not be explained, and the single-parameter contract is fully covered by schema plus description. The remaining gap is disambiguation from the sibling 'get_offer', which the description leaves unresolved.

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 is a single required parameter with 100% schema description coverage ('Offer id from search'), so the schema already carries the semantics. The description restates the same provenance constraint without adding format or edge-case detail.

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 ('Fetch') and resource ('full public details of one akay.ie offer') scoped to a single record by id. However, it does not distinguish itself from the sibling tool 'get_offer', which sounds like it performs the same task, so an agent cannot tell the two apart from the description alone.

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

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

It implies usage by requiring 'the id returned from search', which tells the agent this is a follow-up call after a search. It never says when to prefer this over get_offer, nor which sibling ('search' vs 'search_offers') supplies the id.

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 this as a read-only, idempotent, non-destructive, non-open-world operation. The description adds that it returns public details, the akay.ie link, and ordering instructions, but much of that is also covered by the output schema, so it adds only moderate behavioral context beyond 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 a single well-formed sentence that front-loads the key action and resource. There is no filler, and it communicates the essential scope immediately.

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 one required parameter, rich annotations, and an output schema, the description is largely complete for a read-only single-resource lookup. Minor gaps remain around how to obtain the offer_id and how closed offers are handled, but nothing critical 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 single parameter is fully described in the schema as accepting an offer_id from search results or the akay.ie offer URL. The description restates that the tool accepts an offer_id or URL but does not add syntax, format, or validation details 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 names a specific verb and resource: retrieve full public details of one open offer by offer_id or URL. It implicitly distinguishes a single-offer lookup from the sibling search_offers tool, but it does not explicitly name or contrast with any alternative.

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: call this when you already have an offer_id or URL. However, the description does not explicitly say to use search_offers first to obtain an offer_id, nor does it state when not to use this tool or what happens for closed/nonexistent offers.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), and the description goes further by disclosing what is returned (per-case and per-unit price, currency, code-computed line total, MOQ and stock checks) and, critically, that multiple matching offers produce candidates rather than an auto-pick. That ambiguity-resolution rule is a real behavioral trait an agent could not infer elsewhere.

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

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

Four tight sentences, front-loaded with the action and inputs, then the outputs, then the edge case, then the hand-off. No filler and nothing redundant with the 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 14-parameter, zero-required read tool with an output schema, the description conveys the main flow, the identifier requirement, and the multi-match behavior without needing to explain every return field. The empty-required-list wrinkle (at least one identifier is implicitly needed) and the duty/volume filters are left entirely 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 coverage is 64%, so several of the 14 parameters (units, pack, abv, volume_ml, duty_status, target_incoterm, target_location) rely solely on the schema. The description reinforces the identifier trio and the case-quantity basis plus the optional target-price comparison, but adds no syntax or selection logic beyond that — adequate, not compensating.

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 first sentence gives a specific verb and resource ('Price one product') plus the accepted identifier forms and quantity basis, so the agent knows exactly what capability this is. It does not explicitly distinguish itself from siblings like price_my_list or get_offer, which is the only thing keeping it from 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?

The closing instruction 'Once the buyer is happy with a line, offer request_quote' gives a clear next-step condition and effectively names the alternative for the commit phase. There is still no guidance on when to prefer this over price_my_list (bulk pricing) or search_offers, so the routing picture is only half drawn.

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 readOnly, idempotent, non-destructive, closed-world behavior, so the description does not need to repeat safety traits. It adds useful content-level context (counts, brands, filter values), but says nothing about ordering, pagination, or freshness of the returned data.

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

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

One compact sentence with no filler, and the most important content (categories and their contents) comes first. It is slightly under-specified for a purpose statement, but every clause carries information.

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

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

With an output schema present, the description need not enumerate return fields, and annotations cover the safety profile. However, it omits the basic purpose verb and any hint about how this differs from siblings, leaving the agent to infer when this endpoint belongs in a workflow.

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. The schema is empty by design and the description correctly implies the result set is unfiltered reference data.

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

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

The description names the resource (categories) and its contents (offer counts, top brands, filter values), but never states the action or purpose explicitly. It is not a tautology, but an agent must infer from the tool name that this is a listing/reference endpoint rather than, say, a search or fetch.

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 no when-to-use guidance and never mentions the sibling tools such as fetch or search that an agent might otherwise choose. The implied use case (reference data for category filters) is only loosely discernible from the content listing.

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?

Goes well beyond the annotations: discloses hard caps (100 lines / 20 KB), the full match-status taxonomy so failures are per-line rather than wholesale, and the non-conversion currency policy for totals. That is exactly the behavioral context an agent needs and cannot get from readOnlyHint/idempotentHint.

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 action followed by limits, input formats, return shape and currency rules; every sentence carries information. The enumerated status list overlaps with what the output schema likely already declares, which is the only real slack.

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 an existing output schema, the description need not define return fields, yet it still surfaces the two things that change caller behavior: per-line status semantics and the no-conversion currency rule. Caps and input formats complete the picture for a zero-required-parameter 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?

Explains that `text` accepts one-product-per-line or CSV/TSV with a header, and that `lines` carries product names or EANs, case quantities and optional target prices — meaning beyond the schema's own field descriptions. Nested fields like abv, volume_ml, offer_id and target_incoterm are left to the schema, which documents several of them.

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 (price a buying list of up to 100 lines) and immediately enumerates accepted input shapes and returned per-line data. An agent can distinguish this bulk-pricing tool from get_price or get_offer without opening any schema.

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

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

The bulk-list context and the choice between pasting text or supplying structured lines are explicit, which gives clear guidance on how to call it. It stops short of naming alternatives (e.g. get_price for a single product, request_quote for negotiated pricing), so sibling routing is left 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 declare readOnly/idempotent/non-destructive, and the description reinforces rather than repeats them by naming exactly what is not done: 'Sends nothing, reserves nothing and needs no contact details.' It also adds a real behavioral rule the annotations cannot express — totals are computed per currency and never summed across currencies.

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 dense sentences, front-loaded with the input-output transformation, then the currency rule, then the trigger condition. Every sentence carries information, though the WhatsApp/email and upload-URL detail 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?

An output schema exists, so return values need no explanation. The description covers the input shape, the artifact produced, the currency constraint, and the absence of side effects — everything an agent needs to decide to call it and to explain the result to a buyer.

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 0%, so the description carries the load, and it does: it explains that each line pairs an offer_id with cases, or units when the offer is priced per unit without a case size. The per-currency grouping rule adds semantics the schema lacks. Minor gap: mutual exclusivity of cases vs units is only implied by 'or'.

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

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

States a concrete transformation: confirmed lines (offer_id + cases/units) become a quote request summary plus a CSV for the quote.akay.ie upload endpoint, with WhatsApp/email alternatives. This is a specific verb+resource that no sibling (fetch, get_price, search_offers, price_my_list) could be confused with.

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

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

Gives explicit trigger language — 'whenever the buyer says they want a quote, an order or to buy' — and sequencing advice, 'offer it after showing prices', which implies get_price/search_offers run first. It does not name an alternative tool or a when-not condition, which keeps it just short of 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, idempotent, non-destructive, and closed-world, so the safety profile needs no restating. The description adds the return shape and the id-plus-fetch workflow, but since an output schema exists the field list is partly redundant. It says nothing about result limits, ranking, or empty-result behaviour.

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 with no filler; purpose and return shape are front-loaded and the next-step guidance follows. Every sentence carries information and nothing is repeated.

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 annotations covering safety and an output schema covering return values, the description is close to sufficient, but it omits any contrast with the similarly named sibling search_offers. For a catalogue search tool that omission is the one thing an agent would most want resolved.

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 is a single parameter ('query') whose schema description is just 'Search query', so schema coverage is nominally 100% but the coverage adds little. The description mentions no matching semantics, tokenisation, or the 200-character cap, leaving semantics entirely to the schema. Baseline 3 applies for a one-parameter tool with full coverage.

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?

It gives a specific verb and resource ('Search the akay.ie trade catalogue') and states what comes back (offer ids, titles, URLs), which is concrete rather than tautological. It does not, however, distinguish itself from the sibling search_offers, so an agent facing both tools gets no disambiguation.

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 sentence 'Use fetch with an id for full details' names an alternative tool and the condition that selects it, which is genuine routing guidance. It stops short of saying when to prefer this over search_offers or what query formulations work, so an exclusion rule is absent.

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

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

Annotations already declare read-only, idempotent, non-destructive and closed-world behavior, so the lower bar applies; the description still adds real value by disclosing pagination limits (25 per page, 10 pages per query) and what each offer carries (per-case and per-unit prices in the offer's own currency, pack, duty status, Incoterm, location, stock). It omits error behavior and whether results are ranked or ordered.

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 tightly packed sentences: scope first, return contents second, pagination constraints last. No filler, though the return-contents sentence is list-heavy and could be trimmed given an output schema 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?

An output schema exists so return values need only brief mention, and pagination limits are explicitly given, which is the main operational risk. Some gaps remain around filter combination behavior and the undefined enum values (stock_status, incoterm), but the definition is sufficient to call 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?

With 11 parameters at 55% schema coverage, the description adds useful meaning by giving size/pack examples ('70cl', '6x70cl') and clarifying that currency is per-offer rather than a filter-only concern. However, it leaves several parameters (brand exact-match, origin, location, stock_status, incoterm semantics, page bounds) to the schema or undocumented, so it only partially compensates for the coverage gap.

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 open akay.ie trade offers) and enumerates the search axes plus optional filters, so an agent knows exactly what corpus is queried. It does not differentiate itself from the sibling 'search' tool, leaving some ambiguity about which search variant to pick.

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 word 'open' implies closed/expired offers are excluded, and the searchable facets hint at how to query, but there is no explicit when-to-use guidance and no routing to alternatives such as get_offer, list_categories or the generic 'search'. Usage is implied rather than stated.

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