X402 Git

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

Beyond the readOnlyHint/openWorldHint annotations, it discloses endpoint binding, cost expectations ('cheap call'), conditional behavior with wallet_signature, and the privacy guarantee that address ownership is never revealed without it. It also enumerates the possible price_kind values, which is valuable runtime context.

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

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

Three dense sentences carry all the essential information with no filler. The endpoint and core value are front-loaded, and the optional-signature caveat is clearly separated at the end.

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 the readOnly annotations, an output schema, and full parameter coverage, the description provides everything needed to call and interpret the tool: the path, the data, the optional auth-like parameter, and the privacy boundary. 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?

Schema description coverage is 100%, so the baseline is already strong. The description adds the key semantic link that wallet_signature changes the response semantics, and it implicitly maps owner/slug to the URL path. This exceeds baseline without needing to compensate for sparse 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 a specific operation ('Wraps GET /api/v/:owner/:slug') and the exact data it returns: latest version, publication time, and price. It also clarifies the optional wallet_signature mode, which changes the response to include ownership and price_kind, separating it from the listing/purchase sibling tools.

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 a clear usage context: 'the cheap call to make before every run.' It also warns that without wallet_signature the API never reveals address ownership, which guides call construction. However, it does not explicitly name sibling alternatives or state when to prefer them.

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?

Beyond the readOnly and openWorld annotations, the description adds meaningful behavioral details: the URL is fresh for five minutes, the operation is free forever, entitlement failure returns `not_entitled` rather than a 402, and `wallet_signature` is required for proof of ownership. This is exactly the kind of context an agent needs.

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

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

Four tight sentences, each carrying useful information: the endpoint, the freshness window, the entitlement semantics, and the auth requirement. The most important behavioral facts are front-loaded and there is no filler.

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

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

For a read-only retrieval tool with an output schema and clear annotations, the description covers the purpose, entitlement edge case, URL freshness, and authentication prerequisite. An agent has everything needed to call it correctly and understand its result semantics.

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 schema already documents all four parameters well. The description reiterates that `wallet_signature` is required and ties it to entitlement, but adds little beyond what the schema already provides.

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 identifies the tool's action: wrapping `GET /api/r/:owner/:slug/v/:version` to fetch a fresh download URL for a version the wallet already owns. The title and 'Never sells anything' distinguish it from purchase and other sibling tools.

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 explicit usage context: use it when the wallet already bought the version, it is free forever, and it works even after the listing is retired. It also explains the `not_entitled` case, making it clear when the tool is not applicable, though it does not name sibling alternatives explicitly.

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 substantial behavioral context beyond annotations: free/no wallet, unauthenticated, only latest passing release, and the namespacing of computed vs self-reported facts. This enriches the readOnlyHint and openWorldHint without contradicting them.

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

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

Three compact sentences: endpoint, content inventory, and a key structural note (namespacing). All sentences earn their place, front-loaded with the most decision-relevant facts.

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 read-only manifest lookup with an output schema present, the description covers cost, auth, content, and data separation. Nothing essential for an agent to decide or invoke 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 covers both parameters with examples at 100% coverage. The description only echoes the URL placeholders and adds no new meaning about parameter formats or edge cases, so it rests on the schema's baseline.

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 clear verb ('read') and resource ('public manifest'), enumerates the exact content (file tree, sizes, licence, dependencies, security-scan result, release log), and ties it to a distinct use case (pre-purchase). It is unambiguous against siblings like fetch_release and purchase.

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

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

Provides clear context ('free, unauthenticated', 'read it before you buy') that signals when to invoke it, but does not explicitly contrast with sibling tools or state when not to use it. The guidance is implied rather than explicit.

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 provide readOnlyHint and openWorldHint, indicating the tool is safe and may produce varying results. The description adds important context: it explains that the tool returns a step-by-step skill for agents with wallets and a raw x402 endpoint, and it clarifies the decision logic for agents that cannot sign transactions. However, it does not detail any side effects or error conditions, but given the annotations, the added context is substantial.

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, information-dense sentence followed by a clear directive. It front-loads the key selling point ('Free, no wallet needed') and packs in all critical details without redundancy. It could be improved by breaking into bullet points, but it is still well-structured for an agent to parse.

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 tool has an output schema (not shown here, but indicated), which likely details the return values, so the description doesn't need to. It clearly explains the purposeholistic behavior, including the conditional instructions for agents with/without wallets. The only minor gap is that it doesn't explain what to do if the listing is not for sale, but the description does say it returns whether it is for sale, so that is covered.

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 descriptions cover 100% of the parameters, defining `slug` and `owner` with examples. The description does not add further parameter-level detail beyond the schema, so the 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 clearly states the tool's purpose: to provide buying information for a listing. It specifies the exact resources (listing status, version, price, page, skill, endpoint, server URL) it returns. It is distinct from siblings like `get_listing` and `purchase` by focusing on the 'how to buy' information rather than the action 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 explicitly tells the agent when to use this tool: if the user wants to buy without a wallet, answer with `without_a_wallet`; if the agent can sign transactions, follow `with_a_wallet` or call `purchase`. It also names the `purchase` tool as an alternative for those who can sign, providing clear guidance on usage.

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

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

The description discloses significant behavior beyond annotations: the `isError: true` transport behavior, the meaning of `accepts[0]`, that the server never sees the signing key, the five-minute signed URL expiry, and that access is granted only after a transaction hash. This is far more behavioral detail than the sparse annotations provide.

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 information-dense and every sentence contributes to correct use, but it is presented as one long paragraph. The flow would be easier to parse with short sections or bullets for the 402 sequence, payment argument, and success response, so it loses one point for structure.

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

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

For a tool with no output schema and a complex two-phase payment protocol, the description is remarkably complete: it explains the initial 402 response, the signing requirement, all payment input options, the success response contents, URL expiration, settlement metadata, and the zero-price case. An agent has enough context to invoke the tool correctly in each scenario.

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?

Even with 100% schema description coverage, the description adds meaningful semantics: how `quote_id` must be echoed from the 402 and how stale values trigger `price_changed`, the meaning of `wallet_signature` for buyer-specific pricing, and the equivalence/precedence between `payment_signature` and `_meta["x402/payment"]`. This goes well beyond the schema text.

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 the action (purchase the latest release) and the exact resource/endpoint (`GET /api/r/:owner/:slug`), and details the full quote→screen→verify→settle→grant sequence. This distinguishes it from siblings like `check_version` and `fetch_release` because it is the only one that records a purchase and grants access.

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

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

Provides explicit instructions for the two-call flow: call once without payment to receive the 402, sign it, then call again with the payment payload. It also covers the $0-listing shortcut and which argument wins when both payment forms are present. It does not explicitly mention alternatives among siblings, so it misses the full 'when not to use' guidance.

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

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

Annotations already declare readOnlyHint and openWorldHint, but the description adds valuable behavior beyond those: free/no wallet, the exact fields searched, plain-language query semantics, ordering by match rather than sales/popularity, and the fact that results expose owner and slug. This gives an agent a trustworthy mental model of side effects and result characteristics.

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 dense but every sentence carries operational weight: no-wallet note, search scope, query format, ordering behavior, result fields, and next steps. It is well structured, has concrete examples, and does not waste words.

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

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

Given the output schema exists, the description covers everything an agent needs to invoke correctly: what is searched, how to phrase queries, listing-all behavior, ordering rule, and the follow-on tools. The three parameters are fully described in the schemaable, and the workflow routing to get_listing and how_to_buy rounds out the context.

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%, establishing a baseline of 3, and the description adds meaningful query semantics not in the schema: 'Describe the job in plain words,' concrete examples, and empty-query behavior. The limit and max_price_micro parameters are already well documented in the schema, so the description's extra query guidance pushes this above baseline.

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

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

The description opens with a specific verb and resource: it 'Searches every live listing' across private repos, agent skills, prompt packs, and toolkits. It clearly distinguishes the tool from siblings like get_listing and how_to_buy by focusing on discovery and search rather than details or purchase.

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 strong usage context: 'Free, no wallet needed,' plain-word query guidance with examples, and the 'leave query empty to list everything' fallback. It also outlines the workflow—use get_listing next, then how_to_buy—but it does not explicitly state when not to use this tool or contrast it with a fully named alternative search tool.

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