Cassandra shop

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 non-obvious fact that this is a payment-requirement step, that 'no money moves in this call,' and that paying is a separate action. It does not describe failure modes, authentication requirements, or the shape of the returned payment requirement, which a payment-gated tool would ideally cover.

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 the action and the critical caveat about what the call actually returns. The character limit is stated twice (once in prose, once by the schema), which is minor redundancy, but nothing else 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 multi-step, payment-gated tool with no output schema, the description supplies the essential sequence and the key behavioral caveat an agent needs to avoid misusing the result. It omits what the payment requirement response looks like and how errors surface, leaving a modest 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?

There is a single parameter with 100% schema description coverage, so the schema already documents the question field and its 800-character limit. The description merely repeats the '<=800 chars' constraint and adds no syntax, format, or content guidance beyond it. 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 ('Ask Cassandra one question') and immediately corrects a potentially misleading name by stating that this call does not return an answer but the live x402 payment requirement. That is a precise, actionable purpose. It stops short of explicitly distinguishing itself from any named sibling, so it lands at 4 rather than 5.

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

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

It lays out the required workflow clearly: this call first, then pay to the vault, then POST the transaction signature to /api/ask, with the answer binding to that payment. That is strong context for sequencing the tool correctly. It offers no explicit when-not-to-use or comparison to the sibling tools, which keeps it out of 5 territory.

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 disclosure burden and does so well: it states the call is free, bounded ('One bounded request'), refuses private/loopback/CGNAT targets (an SSRF-safety constraint), and explicitly withholds the fetched body ('never returns the fetched body, only a shape verdict'). These are non-obvious behaviors an agent host needs before calling.

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?

Five dense, front-loaded clauses with zero filler. The core answer is stated first, then cost, then safety/behavioral constraints, then the scope disclaimer — a well-ordered 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?

With no output schema and no annotations, the description must explain behavior and returns; it covers behavior thoroughly and characterizes the return as 'a shape verdict' rather than the fetched body. The exact shape of that verdict is left slightly vague, which is a minor gap given there is no output schema to lean on.

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 there is a single param, so the schema already documents 'Absolute http(s) URL to check.' The description still adds value by constraining semantics — the target must not be private/loopback/CGNAT — which tells the agent what values will be rejected.

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 (check) and resource (a URL's x402/HTTP 402 payment challenge), and frames the exact question it answers: whether a URL returns a well-formed 402 challenge before routing a paid call. The sibling tools (ask_cassandra, get_terms, list_products, shop_vitals) are in unrelated domains, so no differentiation is needed and none is missing.

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 usage context — 'the question an agent host asks before routing a paid call' — and draws a negative boundary with 'This is a free shape check, NOT a conformance report.' It does not name an alternative tool or an explicit when-not-to-use condition, so it falls short of full 5-level 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?

With no annotations, the description carries the full burden and does so well: it discloses that the call is free, that no money moves here, and that the live 402 challenge is authoritative over any written terms. It omits auth requirements and rate limits, hence not 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 purpose and return payload, then behavioral caveats, then id guidance. Dense but every sentence carries information; only minor overlap between the id examples and the 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?

There is no output schema, so the description appropriately enumerates the return contents (amount, asset, network, pay address, next step) and clarifies the authoritative source. An agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so the allowed id values (ask, field_manual, conformance, store listing id) are already documented in the schema. The description repeats these values but adds no syntax or format detail beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb (Get) and resource (LIVE, payable x402 payment terms for a product) with clear scope. It names the exact return payload (amount, asset, network, address, next step), letting an agent distinguish it from siblings like list_products and check_endpoint without opening any schema.

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

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

Gives clear context: it is free, paying is a SEPARATE deliberate step, and ids come from list_products. It does not explicitly state when-not-to-use or name alternative tools for other needs, but the usage condition is well established.

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. "List" implies a read-only operation and it discloses the two notable output traits (exact prices, live sellability) plus cost ("Free"), but says nothing about return format, ordering, or pagination for a shop with many products.

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 zero filler, and the most decision-relevant content (what is listed and its key fields) is front-loaded. "Free" is placed last as a throwaway cost note rather than padding.

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

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

For a no-parameter list tool with no output schema and no annotations, the description covers what matters: the resource, the notable returned fields, and the cost. It stops short of describing the result shape, which is the only real gap given no output schema exists.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. Nothing in the text confuses the empty input contract.

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 this shop's products") and sharpens it with the exact contents returned (prices and current sellability). It is clear what the tool does, though it never explicitly contrasts itself with siblings like shop_vitals or get_terms.

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, so an agent must infer that this is the tool for product data versus shop_vitals or get_terms. The one-word "Free" note does act as an invocation hint, signalling the call carries no cost, which lifts it above a bare 2.

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 add real context: it is a read-only operation, the data is live and public, the treasury figure is an on-chain read that may not always be available ('where available'), and there is no cost. Rate limits, freshness/caching, and failure behavior are not covered, keeping it below 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 sentence that front-loads the action and resource, then lists the three outputs in a compact parenthetical. Every clause earns its place, including the availability caveat and the cost note.

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, no-output-schema tool the description usefully enumerates what comes back (visitor count, wakes to date, treasury balance) and flags the one conditional field, which compensates for the missing output schema. It stops short of describing data freshness or error behavior, but nothing essential to invoking the call is absent.

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 argument semantics to explain; this is the baseline 4 for a parameterless tool. The description appropriately spends its words on the returned fields instead.

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 (Read) and resource (this shop's live public vitals) and enumerates exactly what is returned: visitor count, wakes to date, treasury balance. None of the siblings (ask_cassandra, check_endpoint, get_terms, list_products) overlap with this metrics-read purpose, so an agent can identify it immediately.

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 zero-parameter signature and the 'Free' note make it obvious this is a cheap, always-safe call, but the description never states when to reach for it versus a sibling or whether any precondition is needed. No alternatives or exclusions are named.

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