ACORN GLOBAL

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 structurally. The description still adds real value by disclosing what content is returned and by flagging hedges ('where verified', 'remaining limitations') plus the explicit 'never creates or verifies purchases' boundary, which tells the agent the result cannot be treated as purchase confirmation.

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 compact sentences with the scope constraint front-loaded and a list of surfaced fields that scans quickly. The closing negation is slightly redundant against the readOnly annotation, but it is short and reinforces rather than pads.

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

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

With no output schema, the description does the right thing by enumerating returned content, which is the main completeness need here. However, for a tool with two entirely undocumented parameters, it leaves the agent guessing about the id format and the purpose of the language argument, so the definition is adequate but not sufficient.

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 0%, so the description must carry the semantics of both parameters and largely does not. 'One exact offer' hints that id identifies the offer, but the id's format constraints (slug pattern, 120-char cap) go unmentioned, and the language enum is not addressed at all — worse, 'the deliverable language' in the description could be misread as the language parameter rather than an output field.

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: a 'public read-only purchase guide for one exact offer,' and enumerates what it surfaces (unit amount, official URL, deliverable language, kit contents, prerequisites, limitations). It does not explicitly contrast itself with the closest siblings such as acorn_offer_details or acorn_commercial_boundaries, so an agent must infer the boundary.

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 only implied: 'for one exact offer' signals that an offer id is required and that this is a pre-purchase inspection step. There is no explicit statement of when to choose this over acorn_offer_details or acorn_compare_offers, and no stated exclusions or prerequisites for calling it.

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 fully covered without the description. "No operational access" restates the read-only nature rather than adding new behavior detail such as freshness, scope of the limits, or whether results are static. Modest added value over 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 short sentences with no padding and the read scope front-loaded. The closing fragment "No operational access" is terse to the point of slight ambiguity, but it is not wasted words.

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-param, annotation-rich tool with no output schema, the definition is minimally sufficient but leaves gaps: it does not say what form the limits take or how they relate to the other acorn tools. A sentence on what an agent should do with the result would round it out.

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 and there is nothing for the description to disambiguate. The empty schema with additionalProperties=false is self-explanatory.

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?

"Read public capabilities, safety and checkout limits" names a verb and a rough subject area, so the agent knows this is an informational read. But "capabilities" and "limits" are vague, and nothing distinguishes it from informational siblings like acorn_buyer_guide or acorn_public_catalog. The title's phrasing ("commercial limitations") is more specific than the description itself.

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 when-to-use guidance and no alternative is named, despite eleven sibling tools in the acorn family. "No operational access" hints that this is not the tool for performing purchases, but the agent must infer that rather than being told when to prefer acorn_buyer_guide or acorn_find_offers instead.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: it rejects missing IDs and will not fabricate discounts, totals, orders or delivery guarantees — a real constraint on what the agent can rely on. It says nothing about the shape or size of the returned comparison, which is the remaining behavioral 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?

Two tight sentences with the read/comparison purpose front-loaded and the guardrails after it. The second sentence is telegraphic ("Reject missing IDs; no invented discounts...") but every clause carries information an agent needs. No 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 2-parameter read-only tool with no output schema, the definition is adequate but leaves notable holes: nothing about what a comparison result contains, nothing about how language affects output, and no routing versus the single-offer sibling. It is callable as written, but not fully self-sufficient.

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 0%, so the description carries the burden and only partially meets it: "Reject missing IDs" hints that ids are mandatory and validated, but adds no format or identity semantics beyond the schema pattern. The language parameter is never mentioned, and the 2–4 count bound lives only in the title, not the description.

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

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

The description names a specific action and resource ("Read side-by-side canonical offer records and terms"), which makes it clear this is a multi-offer comparison/read tool. The title adds the 2–4 cardinality. It stops short of naming the sibling it replaces (e.g. acorn_offer_details for a single offer), so it is clear but not fully differentiated.

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?

"Side-by-side" implies comparison usage, but there is no explicit statement of when to choose this over acorn_offer_details, acorn_recommend_offers or acorn_find_offers. "Reject missing IDs" is an error constraint, not usage guidance. An agent must infer the routing decision from the tool name alone.

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 and destructiveHint=false, so the safety profile is largely covered by structured data. The description still earns credit for adding what the annotations cannot: that this is a public-only view, that no checkout session is opened, and that no customer identity is captured. It does not disclose pagination defaults or result ordering, which is a minor remaining 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?

Two tight sentences, front-loaded with the core action and followed by the scoping constraint. Nothing is redundant, though the second sentence packs both a filter rule and a safety guarantee into one clause, which slightly blurs the structure.

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, all-optional search with no output schema, the description covers what is returned (public products) and the critical non-effects (no checkout, no customer record). Missing details on pagination behavior and language selection are modest, since the schema constrains both and defaults are optional.

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 40%, with query and filter documented in-schema; limit, offset, and language carry no description anywhere. The description partially compensates by explaining the direct-vs-scope distinction that the filter enum encodes, but it says nothing about page size, offset semantics, or what the language enum changes. Baseline 3 is appropriate given the partial coverage and partial compensation.

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 ('Read current public products') and adds a scope distinction between immediate Stripe hosted products and quote-based custom services. It doesn't name any of the adjacent siblings (acorn_public_catalog, acorn_offer_details, acorn_compare_offers), so an agent must infer the boundary from the title rather than the 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?

Usage is implied: this is the read-only search for public products, and the 'no checkout is created and no customer is identified' clause signals it is the non-transactional path. However, no alternative tool is named and no explicit when-not condition is given, so the agent gets context but not 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, destructiveHint=false and openWorldHint=false, and the description goes further by stating the link is pre-verified, that payment happens off-tool on Stripe, and that fulfillment/delivery is explicitly NOT part of the response. It does not cover what happens for an unknown or ineligible id, nor whether the URL is stable or expires.

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 return value first and the safety boundaries after; every clause carries distinct information and nothing is repeated from the annotations or schema.

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

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

With no output schema, the description correctly compensates by naming the two returned values (public Stripe URL and listed USD amount). For a two-parameter read tool with annotations already covering safety, the remaining gaps — id semantics, the language parameter, and error behavior — are the only things keeping it from full completeness.

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 0% for both parameters. The description only implies that 'id' identifies the offer ('for one DIRECT offer') without stating the format or accepted values, and the 'language' enum (fr/en) that presumably localizes the returned page is never mentioned at all.

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

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

The description opens with a specific verb and resource: returns the already-verified public Stripe URL and listed USD amount for one DIRECT offer. The scope ('one DIRECT offer', 'already-verified') implicitly separates it from acorn_request_link and acorn_offer_details, so an agent can tell what it does 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?

It gives clear usage context (a human must review and pay on Stripe) and strong negative boundaries: never initiates payment, never buys, never verifies payment, never delivers privately. What is missing is explicit routing — it never names acorn_request_link as the alternative when a link does not yet exist, leaving the agent to infer that from 'already-verified'.

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

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

Annotations already declare readOnlyHint, openWorldHint and destructiveHint=false, and the description usefully reinforces the non-execution/non-download boundary so an agent won't mistake this for a model-running tool. The added license caveat ('License tags are not authorization for commercial use') is genuine context beyond annotations. It stops short of describing result shape or entry contents.

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

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

Three compact sentences, front-loaded with the core read-only search scope and followed by exclusions and the license warning. No filler, though the license sentence is directed at downstream use rather than at calling the tool correctly.

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 three-parameter search with no output schema, the description covers boundaries well but omits anything about what a returned record contains or how results are ordered/paged (relevant given the max limit of 5). Adequate but with a real gap on the discovery output side.

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 only 33% – just the query parameter is documented – and the description adds nothing about the three parameters. It does not clarify what 'kind' selects, how 'limit' bounds results, or what constitutes a valid short public-topic query beyond the schema's own constraint.

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 – 'Bounded read-only metadata search on the public Hugging Face Hub' – with explicit scope (public, metadata-only). This clearly separates it from the sibling commerce tools (offers, checkout, buyer guide) and the other catalog/assistant tools 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 strong negative guidance ('does not execute, download, train, deploy or purchase models'), which tells the agent what this is not for. However, it never states when to prefer this over siblings like acorn_public_catalog or acorn_world_ai_integrations, leaving the positive routing decision implicit.

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 readOnly/non-destructive/closed-world, but the description adds real domain behavior beyond them: it discloses the conditional return shape (exact price and customer link for fixed-price goods vs. an enquiry link when a quote is required) and explicitly states "Never charges a customer." That branch information is not derivable from any structured field and materially affects how an agent presents the 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?

Three short sentences, front-loaded with the action and identifier, followed by the return behavior and the no-charge guarantee. No redundant wording and nothing buried.

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

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

With no output schema, the description does helpfully summarize the two possible return shapes, which is the right instinct. However, for a tool with an undocumented language parameter and no stated behavior on a missing or non-public ID, the definition leaves gaps an agent would hit in practice.

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 0%, so the description carries the full burden, and it only partly discharges it: "canonical ID" gives meaning to the required id parameter, but the language parameter (fr/en enum) is never mentioned, so its purpose and default are undocumented anywhere. The pattern and maxLength constraints exist in the schema but their significance is unexplained.

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?

"Read a public offer by its canonical ID" states a specific verb (read/lookup) and resource (a single offer), and "exact" plus the singular framing distinguishes it from the plural siblings like acorn_find_offers and acorn_compare_offers. It stops short of naming any sibling, so the differentiation is implicit rather than explicit.

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?

"By its canonical ID" implies this is the follow-up call once an ID is known, which is useful context, but the description never states when to choose this over acorn_find_offers or acorn_compare_offers, nor what to do if the ID is unknown. Usage is inferable rather than stated.

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-obvious context: no charge, no authentication, no private access, and the returned links are not meant to be machine-followed. It still omits whether the content is static or refreshed.

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 tight sentences with no filler, and the content scope leads. The specific counts (nine, three) are front-loaded but read as arbitrary without a frame of reference, slightly reducing immediate comprehension.

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 read tool, annotations cover safety, but with no output schema the description should say more about what comes back (for example, a list of named offers with URLs and prices versus a flat link dump). The current text gestures at this with "links" but leaves the return shape ambiguous.

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 meaning for the description to carry. 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?

Uses a concrete verb ("Read") and enumerates what the catalogue contains: nine canonical professional services, three entry proposals, and listed fixed-price Stripe-hosted products. It never states plainly that it returns a catalogue of links, and it does not distinguish itself from siblings such as acorn_find_offers or acorn_offer_details, so an agent must infer the boundary.

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 explicit when-to-use or when-not-to-use guidance relative to the many offer-related siblings. "Links for humans only" is a useful access constraint but functions as a caveat rather than as guidance on selecting this tool.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: results are deterministic (reproducible for the same inputs) and the tool performs no payment, profiling, or final-tax computation. It does not disclose how recommendations are ranked, whether results can be empty, or why determinism matters to the caller.

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 tight sentences with no filler, front-loading the core operation before the exclusions. The density is slightly cryptic ('direct/quote preference' vs. the schema's 'purchase'), but nothing is wasted.

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 six-parameter tool with no output schema and 17% schema coverage, an agent still lacks essentials: what a result looks like (ranked offers? count bounded by limit?), and how the enum options change behavior. The boundary statements are helpful, but the definition is only minimally sufficient to invoke correctly.

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

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

Schema coverage is only 17% (just 'goal' is documented), so the description must carry the load, and it does mention four of six parameters by concept: goal, budgetUsd, delivery, and purchase preference. It does not explain the enum values for delivery (digital/human/any) or purchase (direct/scope/any), nor the unseen 'limit' and 'language' parameters, leaving meaningful gaps.

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

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

The description names a specific action and resource: 'Deterministic public offer matching by a short business goal, optional USD budget, delivery kind and direct/quote preference.' An agent can tell this is a recommendation/matching operation over public offers, distinct in spirit from detail or purchase-link siblings. It stops short of naming the closest siblings (acorn_find_offers, acorn_compare_offers), so the differentiation is inferred 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?

Usage is only implied by the inputs (goal, budget, delivery, preference); there is no explicit 'use this when' statement. With three closely related siblings (find, compare, details) available, the description gives no rule for choosing between recommendation, search, and comparison. The negative constraints ('no personal profiling, payment or final-tax calculation') describe scope limits rather than 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 establish readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds business-level behavior beyond that: it guarantees no lead, order or payment is created and that the URL is official and public, which is exactly the side-effect reassurance an agent needs. It says nothing about auth or rate limits, but those are minor for a pure lookup.

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 with the purpose front-loaded and the disambiguating negation second. No filler, and every clause carries information the agent needs.

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 single-parameter lookup with no output schema, the description usefully states what is returned (a public enquiry URL) and what is not produced (lead, order, payment). The only gap is whether the URL varies per service or how the caller should use it, which is minor at this complexity.

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

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

Schema coverage is 100% and the enum is fully enumerated with a description ('One of three small-scope entries or nine canonical service IDs'). The description adds no further meaning about how the chosen service changes the returned URL, so the schema is doing all the work and 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 gives a specific verb and resource ('Get an official ACORN public free enquiry URL') and immediately rules out the most likely confusion with a sibling ('does not create a lead, order or payment', i.e. not acorn_hosted_checkout_link). It never names that sibling explicitly, so the differentiation is inferred 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?

Usage is implied: use this when you only need a free, non-committal enquiry entry point rather than a paid checkout or offer flow. There is no explicit 'use this when...' clause and no sibling is named as the alternative, so the agent must infer the routing rule from the negative clause.

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 state readOnlyHint, destructiveHint=false and openWorldHint=false, and the description adds genuinely new behavior: results come with contents, language, delivery proof and an 'official human-controlled Stripe link', and that no checkout/payment occurs. It still omits result-count caps (limit max 3), latency and what happens on zero matches, 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?

A single dense sentence front-loads the safety profile ('One safe, read-only call') before the action and the negative guarantee. Every clause carries information, though phrasing like 'real direct-buy offers' and 'listed-unit USD budget' is jargon-heavy for the agent's first read.

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

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

With no output schema, the description usefully substitutes by enumerating what the response explains (contents, language, delivery proof, Stripe link). For a 5-param, 1-required read tool this is close to sufficient; the missing pieces are limit semantics and enum value meanings.

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?

Only 'goal' has schema documentation (20% coverage), so the description must compensate and does so partially: it clarifies goal is a 'business need', budgetUsd is a 'listed-unit USD budget with real direct-buy offers', and touches on language and delivery proof. It never explains the 1-3 'limit' parameter or the digital/human/any enum meanings, leaving meaningful gaps.

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 set (matches a need/budget to direct-buy offers, then explains contents, language, delivery proof and Stripe link) and a clear resource (buyable ACORN products). It is unambiguous what the call returns, but it never names or contrasts the very similar siblings (acorn_find_offers, acorn_compare_offers, acorn_offer_details), so an agent cannot easily tell which to pick from 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?

Usage is only implied: 'matches a business need and optional listed-unit USD budget' suggests the search-and-explain scenario, and 'No checkout created or payment attempted' implicitly routes purchase intent elsewhere. There is no explicit when-to-use/when-not or named alternative, so the agent must infer boundaries from the sibling list.

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, destructiveHint=false and openWorldHint=false, but the description adds genuinely new behavioral context: no connector install, no authorization flow, no purchase, and crucially no live platform verification — so the agent knows the returned data is static documentation, not a validated connection. It stops short of describing the shape or freshness of the returned routes.

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

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

Two sentences, front-loaded with the verb and scope, and the negative constraints are packed into one clause rather than spread out. The long platform enumeration is dense but each name is load-bearing for platform selection.

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?

There is no output schema, so the description should say what an 'integration route' actually is (URL, doc link, step list) and whether all platforms are returned when the parameter is absent; neither is stated. For a single-optional-parameter read tool this is workable but leaves a real gap 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?

With 0% schema description coverage the description must carry parameter meaning, and it partly does by naming the platforms, which map onto the enum values. However it omits 'huggingface-huggingchat' from the list even though that value exists in the enum, and it never explains what omitting the optional 'platform' parameter returns (all routes vs. an error).

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 and resource ('Read official integration routes') and enumerates the ten platforms covered, so an agent knows exactly what domain of content comes back. It does not name or contrast any sibling tool (e.g. acorn_huggingface_search, acorn_public_catalog), which would be needed for 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?

Usage is only implied: the tool is for looking up documented integration paths, and the second sentence rules out install/auth/purchase/live-verification, which functions as a partial when-not. There is no explicit statement of when to pick this over the sibling catalog/offer tools, nor any prerequisite or follow-up guidance.

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