Shoptegrity

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 is covered. The description adds genuinely useful context beyond them: every result carries the backing source, and results are 'not ranked by commission' — a disclosure that materially affects how an agent should interpret ordering.

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 filters, then the two behavioral notes, with no filler sentences. It reads as one dense block rather than cleanly separated clauses, but every sentence earns its place.

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 explanation is unnecessary, and the description covers filter behavior plus the sourcing guarantee. Given the low complexity of a three-parameter browse tool, the only real omissions are the 'limit' parameter and sibling differentiation.

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 burden, and it does for two of three parameters: 'structure' is explained with example values and 'query' is explained as matching name or substituted category. The 'limit' parameter is never mentioned, leaving one gap, but the compensation for the undocumented filters is strong.

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 ('browse alternatives to mainstream shopping') and defines the scope precisely by enumerating the seller structures included (employee-owned, cooperative, credit union, B Corp, family-owned) with a 'cited basis' requirement. It does not, however, differentiate itself from near-identical siblings such as find_alternatives or responsible_alternatives, so an agent cannot tell them apart from the text 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 implied through the filter semantics ('structure filters by kind', 'query filters by words in the name or the category it substitutes for'), which tells the agent how to narrow results but not when to choose this tool over find_alternatives or responsible_alternatives. No exclusions, prerequisites, or alternative-tool routing are 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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds real value beyond them by disclosing the result shape (company match, cited facts on parent/filings/payouts, and what is withheld) and a hard operational limit of 50 items.

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 dense sentences with no filler; the core action is front-loaded and the item examples and 50-item limit follow immediately. Slightly packed with parenthetical detail, 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?

An output schema exists, so return values need not be enumerated, yet the description still characterizes the per-item output. Combined with the item-type guidance and batch limit, an agent has enough to invoke it correctly; only cross-tool routing 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 0% for the single 'items' array, so the description must carry the meaning, and it does: it defines the acceptable item types (products, brands, stores), gives concrete examples ('AirPods', 'Tide pods', 'Walmart'), and states the batch ceiling of 50. Only the array element format details are left implicit.

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 ('Check a shopping or gift list') and spells out what the response contains per item (scored company, cited facts, withheld data). It is clearly distinguishable in scope from siblings like check_deal or check_seller, though no sibling is named explicitly.

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: 'Items can be products, brands or stores' plus the 50-item cap tell the agent this is a batch-resolution tool, but there is no explicit when-to-use/when-not guidance or routing to alternatives such as lookup_brand, get_brand_parent_feed or find_alternatives.

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, idempotent, non-destructive, openWorld), so the description earns credit for adding the substantive behavior: it compares against recorded daily history and emits a named flag for price manipulation. It does not say what happens when no history exists or how a stale/limited history is handled.

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 tight sentences, zero filler, with the core action stated first and the flag detail and input provenance following in priority order.

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 description covers purpose, provenance of the required ID, and the key flag. The one real hole is the semantics of the optional current_price parameter.

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 compensate. It does explain where product_id comes from (responsible_alternatives), but current_price is left completely unexplained — whether it is optional, what happens if omitted, and whether it is compared against history. Half the parameters are still undocumented.

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: judge a sale price against recorded daily price history for a Shopify catalog product, plus the specific flag it can return ('raised_then_lowered'). That distinguishes it fairly well from siblings like verified_deals, though it never explicitly contrasts itself with 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?

Gives clear usage context ('works for Black Friday and Cyber Monday deals') and, importantly, routes the agent to the correct source for its required input: 'product_id comes from responsible_alternatives.' No explicit when-not-to-use or alternative tool is named, which keeps it below 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 cover read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower, and the description still adds real context: results are 'cited' (provenance/evidence attached) and an empty answer means 'no signals found', not 'seller is bad'. That negative-result caveat is exactly the kind of disclosure annotations cannot express. It omits ambiguity handling and any rate/source limitations.

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 core deliverable is front-loaded before the sibling comparison. Slightly compressed to the point of being cryptic in the opening clause, 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?

An output schema exists and annotations cover the safety profile, so the description only needs to characterize the result and its interpretation, which it does: cited signals or a plain no-signals statement, with the negative-finding caveat. 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 description coverage is 0% and the only param is an unlabeled 'name' string, so the description carries the burden. It does add meaning by saying the value may be a seller OR a brand name, which the schema does not convey. It gives no format, casing, or example guidance, so compensation is partial.

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?

Names a specific resource (cited ownership signals for a seller/brand) and explicitly frames it as the same data as lookup_brand re-phrased for a seller, which lets an agent separate it from that sibling. The phrase 'cited ownership signals' is somewhat jargon-y and never unpacked, so the exact payload is only partially clear.

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 a concrete use condition ('for a seller you are about to buy from') and points at lookup_brand as the related tool with the same data. The parenthetical '(not a negative finding)' is genuinely useful interpretive guidance about how to read an empty result. It stops short of stating when NOT to use it, or how to choose between this and lookup_brand when the input is ambiguous (a name could be both).

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, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds real behavioral content beyond them: the empty-list-with-note response and the disclosure that results are not ranked by commission, which signals the ordering is not commercially biased.

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 tight sentences with zero padding. The core purpose leads, the fallback/empty behavior follows, and the sibling routing plus the commission caveat close it out; each sentence carries distinct 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?

An output schema exists, so return-field details need not be in the description, and the annotations cover the safety profile. The description rounds this out with the empty-result case and the commission caveat, though it leaves brand-name input format 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 0% for the single brand_name parameter, so the description carries the burden. It implies a single brand identifier ('for one brand') but gives no format, casing, or matching rules, so it only partially compensates for the 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 ('List alternatives for one brand') and narrows it with two precise scope qualifiers: editor-approved and backed by a cited basis. It also distinguishes itself from the similarly-named sibling browse_alternatives, so an agent can pick between them without opening either 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 alternative tool (browse_alternatives) and the condition that selects it (listing by category rather than by brand). It also tells the agent what to expect when no alternatives qualify, so the caller knows the empty case is not an error.

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 safety is covered. The description adds real behavioral context beyond that: chains/franchises excluded, results not ranked by commission, and the pilot-area coverage caveat for the directory. It stops short of describing result size/pagination.

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?

Purpose and location format are front-loaded, and most sentences carry unique constraints (radius bounds, exclusions, ranking). It runs long as a single dense block with some comma-heavy enumeration, but little 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?

An output schema exists, so return values need not be explained. The description covers location format, category behavior, radius limits, and exclusions, which is nearly everything an agent needs to call it correctly; only result-set behavior (volume/ordering) is unaddressed.

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 does: location format with concrete examples ('55401' or 'Duluth, MN'), radius_km bounds (0.1 to 500, default 25, shops searched within 15), and category narrowing either list. Category acceptable values remain vague (no enum, only implied by the business-type list).

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 (find) and resource (local businesses), and details exactly what is returned: Shoptegrity's directory (co-ops, markets, credit unions) plus independent shops by category across the US. The scope distinction (US ZIP code or town/state) lets an agent differentiate it from brand/deal/alternative siblings without opening the schema.

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

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

Gives clear usage context ('for Small Business Saturday or any local shopping') and a meaningful exclusion ('Chains and franchises are left out'), which tells the agent when this tool is appropriate. It does not name sibling alternatives or explicit when-not conditions, so it falls 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 readOnlyHint, idempotentHint, destructiveHint=false and closed-world scope, so the safety profile is covered. The description adds genuinely useful behavior beyond that: swap fields stay null until an approval/citation exists, and a failed lookup returns the list of valid retailers via the error message.

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 resource definition before the input example and the null/error semantics. The opening is a noun-phrase fragment rather than a verb-led sentence, but there is no wasted text.

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 annotations cover the safety profile. The description closes the two gaps that matter most for a single-param lookup: how to supply the name and how to recover from an invalid one. The one unaddressed gap is that the core concept 'swap' is never defined.

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 must carry the parameter's meaning, and it does supply concrete examples ('Walmart or The Home Depot'). It falls short of specifying exact-name matching, case sensitivity, or whether partial names are accepted, but the examples plus the error-lists-valid-retailers fallback make the parameter usable.

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 precisely: one retailer's cited financial figures plus any editor-approved swap, and clarifies the singular scope ('One major retailer's'). However, it never differentiates itself from siblings like rate_major_retailers or verified_deals, so an agent must guess whether this or a sibling is the right tool.

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

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

There is no statement of when to use this tool versus the many 'alternatives'/'deals'/'ratings' siblings. The only routing help is implicit: the input is a retailer name, and the error response lists valid retailers, which is recovery guidance rather than usage 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 that this is a read-only, idempotent, non-destructive, closed-world operation. The description adds useful behavioral context by explaining that it returns the date, days left, tool recommendations, and occasion-specific retailer links, without contradicting the annotations.

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

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

The description is front-loaded with the tool's purpose and then covers the occasion values, today default, and occasional retailer links. It is compact and every sentence adds information, though the first sentence is long and slightly overlaps the later retailer-link sentence.

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 available, the description does not need to fully document return structure, and it still explains both parameters and the special retailer-link behavior for certain occasions. It is complete enough for an agent to invoke the tool correctly, with only minor room to clarify the exact output shape or 'next' resolution logic.

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 parameter meaning, and it does: it enumerates all occasion values including 'next' and explains that today is an ISO date defaulting to the server's date. This meaningfully compensates for the bare 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 states the tool produces a holiday shopping plan with dates, days left, recommended Shoptegrity tools, and retailer deal links. It is specific about the resource and scope, and implicitly distinguishes itself from sibling tools by saying it recommends which Shoptegrity tools to use at each step rather than performing those checks 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?

The description gives clear context for when the guide applies: Black Friday, Small Business Saturday, Cyber Monday, Giving Tuesday, Christmas, or holiday gifts, with 'next' for the upcoming occasion. However, it does not explicitly say when not to use it or name sibling alternatives such as check_deal or verified_deals.

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, closed-world behavior, so the description does not need to restate safety. It instead adds genuinely new behavioral context: unsourced fields return null and are listed as withheld, missing names produce an error rather than a clean result, and the score is explicitly framed as an opinion. No auth, rate-limit, or pagination details, but none appear applicable to a single-record read.

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 tight sentences that lead with the capability and follow with return contents, usage scope, and the error caveat. Dense but every sentence adds information the agent needs; no filler or restatement of the title.

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 shapes need not be spelled out, yet the description still summarizes them and additionally covers null handling and error semantics. For a one-parameter read tool with full annotations, nothing an agent needs 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?

Schema coverage is 0% and the single parameter has no description, so the description carries the burden. It clarifies that 'name' accepts a brand, store, or company name and implies a single known value rather than a search query. It does not specify matching behavior (exact vs. fuzzy) or format expectations.

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 ('look up one brand, store or company by name') and enumerates exactly what comes back: parent company, ownership type, source links, and a Shoptegrity composite score. An agent can distinguish this from search_top_brands or lookup_brand_integrity without opening a 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?

'Use it for a single known name' gives an explicit usage condition that separates it from browsing/searching siblings. It also warns that a missing name returns an error that is not a negative finding, which prevents a common misinterpretation. It stops short of naming the alternative tool to use when the name is unknown or when integrity details are needed.

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?

Adds real behavioral context beyond the annotations: uncited fields come back null and are enumerated in withheld_claims, and grades/ratings are Shoptegrity opinions rather than sourced facts. That framing meaningfully affects how an agent should interpret and relay results; only the not-found/ambiguity behavior is left unstated.

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 tight sentences, front-loaded with what is returned, then the null/withheld_claims rule, then the opinion disclaimer. No filler, though the parenthetical SEC clause is slightly cramped.

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 needn't enumerate return fields, yet it usefully flags the withheld_claims semantics an agent might otherwise misread as missing data. The gap is the lack of brand_name format guidance and any not-found handling.

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% for the single brand_name parameter, and the description never says whether it expects an exact brand name, a slug, or a fuzzy match. It implies one-brand scope, which is some help, but a format hint is missing.

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 (in-depth cited metrics) and resource (one brand), and enumerates the content: revenue split, labor records, waste, SEC figures. A sibling lookup_brand exists but the description never contrasts the two, so differentiation is left to inference.

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 'in-depth' versus the presumably summary-level lookup_brand; there is no explicit when-to-use or when-not-to-use statement, no prerequisite notes, and no mention of what to do when a brand is unknown.

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). The description adds valuable context: data provenance from SEC filings, editorial approval for ratings/swaps, and that missing values are null (withheld).

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 front-loaded with the core purpose and lists necessary retailers and data fields. The only redundancy is 'Takes no arguments,' which repeats the schema, but overall it remains efficient.

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

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

Given a simple read-only tool with an output schema, the description covers what is returned, data sources, missing value handling, and editorial constraints. Nothing essential 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 has zero parameters; the description confirms 'Takes no arguments,' which is consistent with the empty schema. Baseline 4 applies for no-param tools.

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 specifies the resource (scorecards for major retailers) and lists the exact retailers and data fields included, but it does not explicitly distinguish this tool from siblings like get_retailer_swaps or lookup_brand.

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

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

The description offers no guidance on when to use this tool versus alternatives; it only states what the tool returns and that it takes no arguments. No conditions or exclusions are provided.

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 open-world, so safety is covered. The description usefully adds that results include a recorded price-history comparison and Shoptegrity standing, but says nothing about result volume, ranking, or coverage 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?

A single front-loaded sentence with no filler, though the trailing domain phrase and currency note make it slightly run-on rather than crisply prioritized.

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 spelled out, and annotations cover the safety profile. Still missing is any differentiation from the several sibling search tools and any note on how limit/pagination behave, which matters for a 3-parameter search.

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 must compensate. It clarifies max_price is in USD and ties product to "a product or gift idea," but leaves limit (default 10) and the units/format assumptions of product entirely to the schema title.

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 independent sellers for a product or gift idea," plus what the results carry (price, price history, Shoptegrity standing). It does not distinguish itself from near-identical siblings like find_alternatives or browse_alternatives, which weakens separability.

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?

Only a vague domain cue ("for gift ideas and holiday shopping") is given; there is no explicit when-to-use versus find_alternatives, browse_alternatives, or find_local_businesses, and no exclusions or prerequisites. The agent must guess which of several similar search tools to pick.

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 safety is covered; the description adds value beyond them by disclosing the summary fields returned and the crucial empty-result interpretation. It stops short of describing ordering, paging, or what happens when limit is reached.

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 tightly packed sentences: capability and return payload first, then routing and the empty-result caveat. No filler, and the most failure-prone detail (empty ≠ negative) lands at the end for emphasis.

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 needn't be re-explained, and the sibling routing plus empty-result semantics round it out. The remaining gap is the undocumented limit and grade-value conventions, minor for a read-only browse 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 coverage is 0%, so the description must carry parameter meaning, and it does cover three of four inputs (query as name, category, minimum grade). However 'limit' is never mentioned and the grade format/taxonomy is left unspecified, so an agent still has to guess acceptable min_grade values.

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 the scored-brand table) plus the three filter axes and what each result contains (parent company, payout, grade, ratings). It also distinguishes itself from lookup_brand, so an agent can route without opening either 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 says 'Use it to browse; use lookup_brand for one known name,' naming the alternative and the condition that selects it. It further warns that an empty result means no match rather than a negative finding, which prevents a real misreading of zero results.

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 only cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial behavioral detail beyond them: the 7-day price-history verification rule, exclusion of prices raised before a sale, ordering by largest drop, a no-commission ordering guarantee, and the seller-diversity behavior of max_per_seller. This is rich methodology disclosure an agent cannot get from 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 purpose is front-loaded and each sentence adds distinct information (methodology, filters, ordering). It runs long and dense, but virtually no sentence is wasted, so it stays efficient for the amount of behavior it must convey.

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 need not be described, and annotations cover safety. The description completes the verification semantics and filter behavior well; the only omission is any note on the limit parameter, which is a small residual gap.

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 does for three of four: min_percent_off range (1-90), query filters by title/seller words, and max_per_seller's default of 3 and its purpose. Only limit is left unexplained, a minor gap given its self-evident meaning.

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+resource: it lists products from independent Shopify sellers whose price Shoptegrity recorded as genuinely dropped. It sharply differentiates from siblings (e.g. check_deal/browse_alternatives) by framing the result set as verified drops rather than 'headline discounts,' so an agent knows exactly what this returns.

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 context for when this applies — verified drops for Black Friday/Cyber Monday, real drops vs. headline discounts — which implies the appropriate shopping-research scenario. It does not, however, explicitly name which sibling to use instead for related needs (e.g. check_deal for a single item), so 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.