KlickyMart

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

With no annotations at all, the description carries the full burden. It does disclose the most important behavioral trait — the output is unsigned, KlickyMart never signs or publishes, and proof tags mark a verified purchase — which is genuine value beyond structured fields. However, it says nothing about validation failure behavior, idempotency, rate limits, or what happens when region/proof data is malformed, which matters for a 35-parameter mutation-adjacent builder.

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 key contract — unsigned template, you sign and publish — is front-loaded, and each following sentence adds a distinct rule (location granularity, proof tags, checkout preset). It is dense but not padded; the heavy parentheticals make a few sentences run long, slightly hurting scanability.

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

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

For a complex 35-parameter tool with no annotations and no output schema, the description covers the core behavioral contract but leaves large semantic gaps on parameter meaning and on what the returned template actually contains. It is adequate to start a call correctly, but not complete for invoking the tool reliably across its many optional fields.

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 only 46% across 35 parameters, so the description must compensate, and it only covers a handful: region format, price_seen/shipping/tax for the checkout preset, and proof-tag concepts. Many parameters (fee, agent, steps, walls, blocker, narrative, duration_s, delivery_days, btc_route, rating, strict, the *_shown_before_payment family) get no explanation in either schema or description. It also references proof tags (zap/preimage/cashu/order_hash) that do not appear as named properties in 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 first sentence names a specific verb (returns/builds) and a precise resource (unsigned Nostr kind 422 'shopping experience' event template), plus the scope constraint that KlickyMart never signs or publishes. It also names the sibling submit_review, so an agent can distinguish this tool from the review-submission path 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?

It gives concrete usage context: sign with your own site-specific key and publish to your own relays, optionally POST the signed event to /reviews or the submit_review tool, and location must be ZIP3/US-state/country only. The preset=checkout paragraph adds a clear when-to-call rule ('one call at the payment screen'). It stops short of explicit when-not-to-use guidance or a full comparison with submit_review.

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?

With no annotations, the description carries the burden and does well: it discloses that the result comes from an index, that it never triggers a live crawl, and which verdict classes may be returned. It does not cover permissions, rate limits, or failure behavior beyond the 'error' verdict, but the key behavioral constraint is stated.

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 user-facing question and is appropriately sized for the amount of information conveyed. The long parenthetical list is dense but functional; slightly more structural separation would improve readability.

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 needs to explain return content, and it does: verdict states, checkout depth, pay methods, BTC grade, record time, evidence URL, and reason fields. It is complete enough for an agent to understand what it will get back, though not exhaustive about field formats.

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

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

Schema coverage is 100%, so both the required domain and optional zip are fully documented in the input schema. The description adds only that the lookup is for 'one domain' and does not mention the ZIP landed-cost behavior, so it meets the baseline rather than extending parameter 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 clearly states a specific lookup: a verdict for one domain from the index. It enumerates verdict states and returned fields, making the resource and scope clear. It does not explicitly name the sibling alternative such as recheck_domain, so it stops short of 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 question 'Can my agent shop here?' and 'from the index' imply the usage context, and 'Never triggers a live crawl' hints that this is a cached lookup. However, it does not explicitly say when to use this versus recheck_domain or other siblings, nor does it state exclusions.

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

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

With no annotations, the description carries the full burden and does substantial work: it discloses that verified-402 means one unauthenticated request received a real HTTP 402 challenge, that no payment was ever made, and that agent-refusing stores surface as findings rather than options. Remaining gaps are pagination, result ordering, and 'Index only' freshness, which are not spelled out.

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?

Dense but front-loaded: the resource scope comes first, then the item shape, then the verification semantics, then the exclusion rule. The field-list sentence is long and jargon-heavy but earns its place as a substitute for the missing output 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?

For a 4-param, no-annotation, no-output-schema discovery tool, the description covers what an agent needs: what is searched, what comes back (agent_native fields), what verified means, and how refused stores are handled. The undefined 'limit' and absence of paging behaviour are the only material omissions.

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 25%, so the description must compensate — and it does for the critical enum: it defines verified-402 vs claimed, which directly governs rail_status, and enumerates the category space. It also explains the agent_native fields returned per item. Only 'limit' is left undefined in both schema and 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 opens with a precise resource definition — agent-payable stores without browser checkout — and enumerates the categories (L402/x402 APIs, VPN, eSIM, VPS, gift cards, nostr). This clearly separates it from generic siblings like search_merchants or find_offers. It lacks an explicit verb and never names a sibling, so it falls short of 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?

Use is implied by the domain framing and the closing 'Index only', which signals a curated-index lookup rather than live crawling. However, there is no explicit when-to-use or when-not-to-use guidance, and no pointer to find_offers / find_alternatives / search_merchants as 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?

With no annotations, the description carries the full burden and does well: it discloses the ranking factors, that turned_away stores are returned with reasons, that blocked stores rank last and default to excluded, and that the tool is index-only and never crawls. It omits auth/permission requirements and any latency or freshness characteristics, which keeps it short of a 5.

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

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

Front-loaded with the core question, then inputs, then return shape, then a one-clause caveat ('Index only; never crawls'). Sentences are dense but every clause carries information; the ranking-factor list is long but tells the agent how results are ordered.

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 10-parameter, no-output-schema tool, the description covers the return payload (stores with evidence URL, ranking dimensions, plus turned_away with reasons) and the key defaults. Nothing critical is missing, though the meaning of the pay enum and the limit parameter are only covered by 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 70%, and the description adds real meaning beyond it: category accepts product words that resolve to a finer sub, zip adds landed cost per store, guest excludes account-required stores, and the two include_* flags have documented defaults and semantics. pay, limit, and domain are left to the schema, which is acceptable given their self-explanatory enums/types.

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: find in-map stores that sell a given product family, with a clear 'where else can my agent buy this' framing. It distinguishes itself by scope (index-only, alternative stores) but never names the sibling tools (search_merchants, find_agent_native, check_domain) it complements, so differentiation is inferential 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?

Explains the accepted inputs clearly (a blocking domain and/or a category or product word) and states the product-word resolution rule (headphones -> audio). It also gives conditional guidance for include_indirect ('with pay=btc/lightning') and the default for include_blocked. What's missing is explicit routing: no statement of when to prefer this over search_merchants or find_agent_native.

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?

With no annotations, the description still discloses meaningful behavior: data source (schema.org JSON-LD or Shopify JSON), returned fields, and the distinction between cached observed offers and a live uncached Shopify Catalog search. It stops short of stating read-only status, permissions, 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?

The description is compact and front-loads the core resource and return fields before covering matching and optional behavior. It is dense but not padded, though the semicolon-heavy structure could be easier to scan.

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

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

For a 9-parameter tool with no annotations, no output schema, and 0% schema description coverage, the description is incomplete. It covers the main matching fields and live/zip behavior but omits several filter parameters and does not explain defaults or result limits.

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 description only explains five of nine parameters: gtin, mpn, q, zip, and live. Important filters such as domain, in_stock, max_price, and limit are left undocumented in both the schema and 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 clearly states that the tool finds product-level offers observed on store pages, including the data source and returned fields. However, it does not explicitly differentiate itself from siblings such as get_landed_price, find_alternatives, or search_merchants.

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 implied usage guidance by explaining matching via gtin, mpn, or q, and notes that zip and live alter behavior. But it does not specify when to prefer this tool over related siblings or when not to use 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?

With no annotations, the description does carry useful behavioral disclosure: 'stopping at the payment screen, never submitting' tells the agent there are no purchase side effects, and the blocker enum discloses the failure taxonomy it can return. However, it doesn't say whether the call triggers a live probe or reads a cached result, what latency/cost that implies, or what happens when domain is unknown.

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?

It is a single sentence with no filler, but the trailing parenthetical enum dump is bulky and the key framing ('what this returns, and that it never submits payment') is buried mid-sentence rather than front-loaded.

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?

No output schema exists, so the description is right to enumerate the returned fields and blocker values — that is the strongest part. Missing: the exact form of the domain input and whether results reflect a fresh probe or stored data, both of which an agent needs before calling.

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 required parameter, so the description must compensate and largely doesn't — 'for a store' only hints that domain identifies the target. It does not clarify whether domain is a bare hostname, a URL, or a store record key, which is the main ambiguity here.

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 (checkout steps, first blocker, landed-cost signals) but is written as a noun phrase describing the payload rather than stating what the tool does. It never distinguishes itself from nearby siblings such as get_landed_price or get_record, leaving the agent to infer that this is a checkout-flow probe result rather than a price lookup.

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, no prerequisites, and no naming of alternatives — even though get_landed_price and check_domain sit in the same sibling set and plausibly overlap. The agent must guess the scenario (checkout feasibility analysis) from the content list 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?

With no annotations, the description carries the full burden and discloses meaningful behavior: it searches KlickyMart-observed offers and optionally the live Shopify Catalog (never stored), returns specific fields including conditional est_total, and explains unindexed stores. It stops short of stating auth needs, rate limits, or explicit read-only safety.

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 action ('One call: a product's landed price at a US ZIP') and every clause adds useful detail about sources, returns, or edge cases. It is dense and long but not wasteful; light restructuring could improve scanability.

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

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

The description thoroughly explains return values and source behavior, which is important because there is no output schema. However, for a 14-parameter tool with low schema coverage, it leaves too many input parameters undocumented and offers no sibling-tool routing guidance.

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

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

There are 14 parameters with only 29% schema description coverage. The description adds meaning for zip and live, but leaves most parameters—q, mpn, url, gtin, type, limit, domain, in_stock, condition, max_price, max_landed, brand_strict—unexplained, so it does not compensate for the low schema 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?

The description states a specific verb and resource: fetching a product's landed price at a US ZIP by searching offers and optionally the live Shopify Catalog. It is clear what the tool does, but it does not explicitly distinguish itself from sibling tools like find_offers or get_checkout_map.

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 by 'a product's landed price at a US ZIP' and the live=true behavior, but the description gives no explicit when-to-use vs when-not guidance and does not name alternatives such as find_offers. An agent must infer the selection criteria.

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?

No annotations are provided, so the description must carry the full behavioral burden. It does not say whether the lookup is read-only, what happens if the domain is unknown, what authentication or rate limits apply, or what data is returned.

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?

It is a single, front-loaded sentence with no filler. The key constraint — one record, looked up by domain — is immediately visible.

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 one-parameter getter with no output schema, the description is operationally usable but thin. It omits response shape expectations, not-found behavior, and read-only semantics, which are especially important given there are no annotations.

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 schema only types domain as a string. The description adds that domain is the merchant domain used to identify the record, which is meaningful but minimal; it does not specify formatting, normalization, or lookup behavior.

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

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

The description states a clear verb and resource (fetch one merchant record) plus the lookup key (domain). It implicitly distinguishes itself from list-oriented siblings like search_merchants by specifying 'one' and 'by domain', but it does not explicitly name an 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?

The single-record, domain-keyed nature implies when to use it over search_merchants, but there are no explicit when-to-use or when-not-to-use instructions. An agent can infer the distinction, but the definition does not guide it directly.

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?

With no annotations, the description carries the full behavioral burden. It usefully discloses that reviews are signed claims by pseudonymous keys and are not verified by KlickyMart, but it omits read-only status, return format, pagination, and ordering behavior.

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

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

The description is a single, front-loaded sentence with no wasted text. However, the cryptic 'Kind 422' phrasing reduces clarity despite the brevity.

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 retrieval tool with no annotations, no output schema, and an undocumented parameter, the description is too sparse. It should explain what the domain parameter expects and what kind of review data is returned.

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 'domain' parameter. The description says reviews are 'of a merchant,' which loosely implies the parameter identifies a merchant, but it does not explain that the value is a domain name or give any format guidance.

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

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

The description identifies the resource as merchant reviews and adds provenance detail, but it lacks an explicit verb and uses the cryptic phrase 'Kind 422,' which an agent may not understand. It distinguishes itself from submit_review only implicitly by the name 'get_reviews'.

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 guidance on when to use this tool versus alternatives such as submit_review or search_merchants. The only hint is that it operates on a merchant, but no context, prerequisites, 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?

With no annotations, the description carries the behavioral burden and does disclose important operational traits: per-store and overall rate limits, plus the throttled response with cached result and next_allowed_at. It does not mention permissions or normal return shape, but the key behavioral constraints are present.

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 concise sentences with no filler, and the core action is front-loaded ahead of rate-limit details.

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?

No output schema or annotations exist, so the description should explain more about return values and permissions. It covers the important rate-limit and caching behavior but leaves the normal response and domain format unspecified.

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 only parameter is an undocumented string named domain, and schema description coverage is 0%. The description references 'store' but does not define whether domain expects a hostname, URL, store ID, or another format.

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

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

The description states a specific verb and resources: re-read robots.txt and home-page status for an indexed store. It is clear what the tool does, though it does not explicitly name the sibling check_domain or explain when an initial check differs from a recheck.

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 for indexed stores, and rate limits are given, but there is no explicit guidance on when to use this versus check_domain or when not to use 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?

With no annotations, the description carries the full burden of behavioral disclosure. 'Search' implies a read operation, but it says nothing about pagination, default limits, result contents, permissions, or rate limits for a 27-parameter tool.

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 sentence is short and front-loaded, but it is under-specified rather than genuinely concise. For a tool with 27 optional filters, this one-liner omits nearly all structurally important 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?

A complex 27-parameter search tool with no annotations and no output schema requires substantially more description. The current text leaves behavior, parameter usage, and result shape almost entirely 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 only 44% across 27 parameters. The description adds no parameter meaning beyond the opaque external reference to 'GET /q,' leaving most filter semantics, defaults, and interactions 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?

The description states a clear verb and resource: 'Search KlickyMart merchant records.' It is specific enough for an agent to understand the core operation, but it does not distinguish this tool from siblings like find_agent_native or find_offers.

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 only usage clue is 'same filters as GET /q,' which is an external API reference rather than guidance. There is no statement of when to use this tool, when not to use it, or which sibling tools are 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?

With no annotations, the description carries the burden and does disclose security constraints (never send a secret key), a business rule ('only visit counts toward the chart'), a leniency rule ('legacy attempt accepted'), and partial return info (the reply includes basis and counts_toward_chart). It omits the dry_run behavior and any failure/validation-error semantics, which is the main 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?

Information is front-loaded correctly (purpose, then requirements, then optionals, then tips), but it is delivered as a single dense run-on paragraph mixing tag syntax, enum lists, and operational advice. Nearly every clause earns its place, yet bullet-style grouping of the enum values would make it far more scannable.

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 nested-object event tool with no output schema and no annotations, the description covers the critical validation vocabulary and even previews two reply fields. It falls short only on the unexplained dry_run flag and on what a rejected event looks like.

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

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

The schema only describes the event blob and leaves the tag vocabulary entirely implicit (0 formal enums), and the description compensates heavily by spelling out the store tag formats, all valid depth values, basis values and their default, and the amount variants. The cost is that dry_run is never mentioned anywhere, leaving one of the two parameters 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 ('Submit a kind 422 shopping-experience note or review') plus the precondition that it must already be signed locally. This distinguishes it from build_experience_note, which is named as the tag-construction step, though the description never explicitly contrasts the two in one clause.

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 clear workflow: build tags with build_experience_note, sign locally, then submit here, and warns 'never send a secret key.' It also says a store tag and depth-or-rating are required, which amounts to preconditions. It does not state when NOT to use it or what happens on rejection.

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?

With no annotations, the description carries the full burden and does so well: facts come from a gated crawl respecting robots.txt and ToS, domains are normalized to the bare registrable domain (paths/queries/affiliates/subdomains stripped), new stores land as trust_tier=unverified, and look-alike/spam submissions are flagged with a reason rather than hidden. Rate limits and the dry-run escape hatch are also disclosed.

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?

Dense but front-loaded: purpose first, then data provenance, normalization, return shape, tier semantics, limits, dry-run, and the event alternative. Nearly every sentence carries information, though the paragraph is packed enough that scanning is harder than it needs to be.

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?

No output schema exists, yet the description supplies the full return shape ({id, domain, status: queued|duplicate|rejected, reason, trust_tier}), including the enum-like status values and the unverified default. For a 7-parameter, nested-object, zero-annotation tool, 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 already 86%, so the baseline is 3; the description adds real meaning beyond it by framing the inputs as 'only the domain, a category hint and an optional note' and explaining that agent_name is stored only as a salted id. The event alternative's required tags (["r", domain], ["t", category], optional ["proof", url]) are spelled out, which the nested-object schema does not do.

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: 'Suggest a store KlickyMart has not indexed yet,' which makes clear this is a write-side submission of new merchants. The 'not indexed yet' qualifier implicitly separates it from search_merchants/check_domain, but 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?

Gives concrete operational context: dry_run=true validates without storing, and an alternative path exists via a signed kind 1423 event. It also states hard limits (10/day, 50/week per submitter and per salted network hash). It does not explicitly say when to prefer this over check_domain or recheck_domain.

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?

With no annotations, the description carries full burden and does well: it discloses the trust boundary explicitly ('KlickyMart never generates, holds or sees seeds, funds, NWC secrets or Cashu tokens') and flags that mint risk is discussed. It stops short of stating outright that the tool performs no side effects and returns static informational content, so a 4 rather than 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?

Two sentences, front-loaded with the resource and its scope, then closed with the custody guarantee. The parenthetical backend list is dense but each entry earns its place by helping an agent recognize their intended setup path.

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 informational tool with no output schema, the description covers topic scope, audience, and safety posture. It doesn't say what the return shape is (single document vs. sections) or whether the content is static vs. live, but nothing needed for correct invocation is missing.

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

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

Zero parameters with 100% schema coverage; the baseline for a parameterless tool is 4. Nothing in the description needs to explain inputs, and none are implied.

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 resource ('Non-custodial wallet setup guide for agents') and enumerates the covered topics — Nostr key, Lightning backends (NWC, Alby Hub, phoenixd, LNbits), lud16 tips, Cashu mint risk, checklist. This clearly separates it from the transactional siblings like find_offers or get_checkout_map. It lacks an explicit verb, but as a static guide tool that is a minor gap.

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: an agent needs this when setting up a wallet to receive tips or pay, since the description mentions lud16 for tips. However, it never states when to use this versus other tools, nor any prerequisites or exclusions. The inference is reasonable but left to the agent.

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

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

With no annotations, the description carries the full burden and does disclose important limits: the result is unsigned, the service does not act on watches, and it never signs for the user. It still omits side effects, permissions, and return-shape behavior beyond the unsigned-template note.

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 short and front-loads the draft/not-served status before the behavior. The internal 'GO D8' token is unexplained, but otherwise there is little 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?

For a five-parameter tool with no annotations, no output schema, and no schema descriptions, the description is far from complete. It provides useful caveats about signing and availability but does not give enough parameter or return context for an agent to invoke it 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?

There are five parameters with 0% schema description coverage, and the description does not explain any of them. 'Price/stock changes' loosely hints at max_price or in_stock, but gtin, note, and domain are entirely 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?

The description states a specific return artifact: an unsigned kind 420 watch template for price/stock changes. However, 'kind 420' is unexplained jargon, and the draft/not-served framing leaves the practical purpose ambiguous for an agent unfamiliar with the domain.

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 notes that the tool is a draft and not served yet and that KlickyMart does not act on watches, which implies it should not be relied on. But it gives no explicit when-to-use guidance and does not point to any sibling alternative.

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