alalanet — check before you pay

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

Annotations already cover read-only, open-world, and non-idempotent behavior, and the description adds genuinely non-derivable context: the advice field's full value set (unknown_key through established and caution_disputed) and, importantly, that profile text is agent-authored and must be treated as data rather than instructions. It doesn't mention freshness or cost of the lookup, which is a minor gap given openWorldHint.

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 the returned content front-loaded and the security caveat last, and nothing is padded. The fragmentary, list-like phrasing ('how long it is known, how many receipts...') is efficient but borders on cryptic.

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 the return shape needn't be explained, yet the description still summarizes the meaningful fields and enumerates the advice values an agent would branch on. Combined with the prompt-injection warning, that is nearly everything needed to call a single-parameter read tool correctly.

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

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

Schema coverage is 100% and the parameter description already specifies 64 hex characters. The description reinforces that this is a Nostr pubkey in hex, which is slight added framing, but introduces no new syntax or constraints beyond the schema — 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 opens with a concrete metaphor plus specifics: it returns a 'passport' for an agent key, covering how long the key is known, confirmed/disputed receipt counts, and reputation. That is enough to distinguish it from siblings like check_service or check_artifact, though the telegraphic phrasing makes the agent piece together the full purpose from the parenthetical list.

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 when-to-use signal lives in the title ('before dealing with it') and is only implied in the description, which never names an alternative such as get_attestation or preflight_payment or states exclusions. The context is inferable but not spelled out in the description text itself.

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 a read-only, open-world, non-idempotent lookup, so the bar is lowered; the description still adds real value by disclosing what is returned (signer identity, publisher standing, hash conflict detection) and the five advice verdicts. The conflict case — same name@version signed with another hash meaning possible tampering — is behavior an agent could not infer from annotations alone. It does not explain why the call is non-idempotent (results change as new signatures appear), a minor 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?

Opens with the trigger condition, follows with the input requirement, then the return semantics and the enumeration of advice codes. Every clause carries information; nothing is padded or repeated from 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?

With an output schema present the description need not detail return structure, and it still summarizes the key verdicts. For a single-parameter verification tool this is nearly complete, with only the non-idempotent behavior and any failure modes for malformed or unknown hashes left unstated.

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 the baseline is 3; the description earns an extra point by stressing 'the sha256 of the exact file', which tells the agent the hash must be of the precise artifact rather than a package name or a manifest, a distinction the schema's 'sha256 of the artifact' leaves ambiguous.

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 who signed) and a specific resource (a release artifact identified by sha256), and the scoping phrase 'skill, MCP server or package' separates it from siblings like check_agent, check_service and get_attestation. Its title and description together let an agent pick it 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?

'Before installing a skill, MCP server or package' gives a clear triggering moment and correctly implies the pre-install verification context. It stops short of naming an alternative or stating when not to use it (e.g., for already-installed or self-built artifacts), so it is clear context without explicit 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?

Beyond the readOnlyHint/openWorldHint/idempotentHint annotations, the description discloses rate limits (100 free default checks a day, 5 live checks a day), that live=true produces a signed logged attestation usable as evidence, and — importantly — that an unknown URL joins the public catalogue, which reconciles a side effect with the read-only claim. It also encodes the decision semantics of the advice codes (ok/ok_requires_auth vs caution_* vs avoid_*), which annotations cannot express. It stops short of saying how the default 'recent check' cache goes stale or what happens when both id and url are refused.

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 front-loaded with the trigger conditions and the parameter choice, then the return contract, then the cost/quota model — a sensible order. The long parenthesised enumeration of advice codes makes it a dense block, but each code carries decision value rather than 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 three-parameter, output-schema-backed check tool, the definition covers invocation (url vs id), cost model (free vs live quotas), side effects (catalogue admission), and how to act on the result. Nothing an agent needs to call it correctly or interpret the advice field 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 100%, so the baseline is 3; the description adds some meaning by tying 'live' to the free-tier quota and the evidentiary value of the signed receipt, and by clarifying that unknown URLs are probed and classified as x402 or MCP. Some of this repeats the schema wording ('signed, logged receipt', 'any URL works'), so the gain is modest rather than large.

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 pair — check an x402 endpoint or MCP server — and immediately scopes it ('before the first payment', 'before connecting to an MCP server'). It explicitly differentiates from siblings by pointing to find_service for the id and preflight_payment for the final per-402 go/no-go.

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?

Three concrete trigger conditions are named: before first payment, before connecting to an MCP server, and whenever a call to it fails. It also names the alternative for the adjacent decision ('For the final go/no-go on a specific 402, use preflight_payment'), so the routing boundary is 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?

The annotations establish that this is a non-read-only, non-idempotent, non-destructive, closed-world write, and the description adds genuinely new behavioral facts: the return payload shape, that the bearer token is shown exactly once, that it only activates once paid, and that it must go into the operator's secret store. These are real consequences an agent could not infer from the schema. It does not address what happens on repeat calls (the non-idempotent hint implies duplicate invoices) or any expiry of the unpaid invoice.

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

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

Two tight sentences, with the core action and return values front-loaded and the safety constraint and secret-handling obligation following. Every clause carries operational weight; there is no restated schema or 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?

An output schema exists, so the description does not need to enumerate return fields, yet it highlights the two that matter for a payment flow. For a 2-parameter, high-consequence spend tool, it covers approval gating and secret handling, which are exactly the risk points an agent needs before invoking.

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 both parameters carry their own descriptions (plan: pro/team/seller; network: tron/solana/ethereum), so the baseline is 3. The description adds only indirect meaning, that the chosen plan determines the exact USDT amount, without saying anything about network-specific addressing or how pay_to varies by network.

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 ("Create an invoice") and immediately names the concrete payload: pay_to, the exact USDT amount, and a one-time bearer token. That is far more than a restatement of the title, and the payment semantics distinguish it from read-only siblings like invoice_status. It stops short of naming invoice_status as the follow-up or list_plans as the way to choose a plan, so sibling differentiation is implied 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?

"Only call when your operator approved the spend" is a clear, actionable precondition that excludes speculative calls, and the token storage instruction gives the agent a post-call obligation. What is missing is routing guidance: the sibling list_plans exists and plan is a required enum-like string, yet the description never says to enumerate plans first, nor does it point to invoice_status for checking payment.

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

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

The annotations already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context that annotations can't carry — results are ranked by liveness and 'real paid usage' — but the remainder of that sentence (status, price, pay_to, uptime) simply enumerates return fields already covered by the output schema.

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

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

Two tight sentences with the core purpose front-loaded and no filler. The second sentence loses a little value by restating return fields that the output schema already defines, but it also introduces the ranking concept, so the space is not 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?

This is a simple four-parameter search tool with full schema coverage, annotations covering the safety profile, and an output schema documenting the return shape. The description covers what it searches, what it searches over, and how results are ordered — enough for an agent to call it correctly. Only explicit routing to sibling tools 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?

Schema description coverage is 100%, so every parameter including query, protocol, only_alive, and limit is already documented with examples and defaults. The description's phrase 'by what they do' loosely reinforces the query parameter's semantics but adds no syntax, formatting, or filtering detail beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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 uses a specific discovery verb ('Search') against two named resource classes ('x402 paid endpoints and remote MCP servers') and scopes it to capability ('by what they do'). This implicitly but clearly separates it from sibling tools like check_service and watch_service, which operate on a single already-known service rather than discovering one.

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 — you call this when you need to find a service matching a capability — but there is no explicit when-to-use vs when-not guidance and no sibling named as the alternative. An agent must infer that this is the discovery step that precedes check_service, preflight_payment, or watch_service.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds meaningful behavior beyond that: the payload is signed by a specific server key and accompanied by a transparency-log inclusion proof, and the result is intended for offline verification — telling the agent the response is self-contained and auditable. It does not explain why idempotentHint is false for what appears to be a pure lookup, which is a small unexplained 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?

One sentence, front-loaded with the verb and returned artifact, with the purpose clause trailing. Nothing is redundant or padded.

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 the description need not describe return values, and one fully documented parameter keeps the interface simple. What remains missing is the provenance of the event_id and the relationship to submit_signed_event, which an agent would plausibly need to chain the two calls.

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

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

Schema coverage is 100% and the single parameter already documents its format ('the attestation event id (64 hex chars)'). The description adds no additional constraint such as where the id comes from or how to obtain one, so it neither helps nor hurts beyond the schema baseline of 3.

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

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

The description names a specific verb ('Fetch') and two concrete resources — a signed Nostr statement from the alalanet server key and its transparency-log inclusion proof. An agent can tell this apart from the sibling set, which contains no other retrieval-by-id tool for attestations. It stops short of naming the complementary write tool (submit_signed_event), so differentiation is implied rather than stated.

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

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

The phrase 'for offline verification or audit' supplies a use case, which is more than nothing. However, there is no explicit when-to-use trigger (e.g. after submit_signed_event, or when a payment/artifact receipt must be independently verified) and no stated exclusions or alternatives among the many check_* siblings.

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 readOnlyHint annotation it discloses the status model (open/paid/expired/review), that the bearer token becomes usable on paid, that tx_hash gets set, confirmation latencies per chain (TRON/Solana ~1 min, Ethereum ~15 min), and a rate-limit instruction. It does restate 'read-only' which the annotation already covers, but the added behavioral context far exceeds that.

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 trigger condition and uses an efficient semicolon-enumerated status list. Slightly dense in a single block and the 'read-only and free' clause duplicates the annotation, but no sentence is genuinely wasteful.

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

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

For a single-param polling tool with an output schema present, the description supplies everything an agent needs: precondition, cadence, status interpretation, and next actions per status. Nothing material 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 100% and the schema's own property description already says 'invoice id returned by create_invoice', so the description's instruction to pass the invoice_id from create_invoice adds little new meaning. Baseline 3 applies where the schema does the heavy lifting.

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 ('learn whether the plan is active') scoped to a lifecycle position ('after create_invoice, once the USDT transfer was sent'), which clearly separates it from create_invoice and the other check_* siblings.

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 when to call it (after create_invoice following the USDT transfer), what to do in each outcome (expired means create a new invoice; review means manual match), and imposes a concrete polling cadence ('poll at most once a minute').

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and idempotentHint=false, so the safety profile is partly covered. The description adds genuinely new behavior: it performs exactly one unpaid request, inspects the live 402 response rather than the listing metadata alone, and returns graded pass/warn/fail results with concrete fixes. It does not discuss rate limits, auth requirements, or failure modes when the endpoint is unreachable.

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 opens with the audience and action, then uses a compact parenthetical list of validation targets. Dense but every listed item is substantive rather than filler; the only cost is that one long sentence demands careful parsing.

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 the return shape needn't be spelled out; the description still summarizes the pass/warn/fail outcome and that fixes are included, which is the right level. For a two-parameter, read-only diagnostic with full schema coverage, the only real gap is guidance on prerequisites (ownership of the endpoint, reachability).

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% with only two parameters, both fully described in the schema (https URL; GET/POST matching the listing). The description adds no syntax, format, or constraint detail beyond that, so the baseline of 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 (lint/check) against a specific resource (your own x402 endpoint) and names the audience ('For sellers'), plus enumerates the concrete spec facets validated (v2 header, v1 body, CAIP-2 ids, payTo, EIP-712 domain, feePayer, bazaar, CORS). This is clearly distinguishable from siblings like check_service or preflight_payment, which operate on other targets.

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?

'For sellers' scopes the audience, and 'request an x402 endpoint once without paying and check its 402' establishes the pre-listing validation scenario. It stops short of explicit routing: it never says when to prefer this over preflight_payment or check_service, nor when not to use it (e.g., endpoints you don't own).

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is partly covered; the description adds useful cost and side-effect context ("takes no arguments, changes nothing, costs nothing") plus the operator-approval gate before spending. However, idempotentHint=false on a tool described as changing and costing nothing is unexplained, and nothing is said about whether the plan list is stable or cacheable.

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 trigger condition is front-loaded, and the return contents, next step, and alternative follow in a logical sequence with no filler. It is dense but slightly overlong, enumerating return fields that the output schema already defines.

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-argument read tool with an output schema and read-only annotations, the description covers triggers, contents, cost, and the follow-up path to create_invoice. Its only redundancy is restating return fields the output schema already supplies, which adds length rather than gaps.

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 zero parameters the baseline is 4, but the description only restates the empty schema with "takes no arguments" and adds no further semantics to interpret. That is a confirmation rather than added meaning, so it sits just below the no-param 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 names the specific resource (free limits, paid plans, payment networks) and what each record contains (id, USDT price for 30 days, daily limits, watched services, contract address). It is immediately distinguishable from siblings like create_invoice and check_service.

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 two concrete trigger conditions (a daily-limit failure, or an operator asking about cost) and names two alternatives: create_invoice for buying a plan, and the x402 per-check path at $0.002 for going without a plan. When-to-use and when-to-use-something-else are both 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?

Beyond the standard hints (readOnlyHint, idempotentHint), the description provides critical, non-obvious technical details such as the specific event types required for reading (27235) and writing (30420), and the data capacity limit (1 MB per key).

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?

Despite its density, the text is highly efficient. Every clause contributes vital information—be it cryptographic requirements, functional modes, or size limits—without any superfluous wording.

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 complex, secure, and technical nature of the memory service, the definition is exceptionally complete. It dictates the required identity proof, capacity, and the exact conditions for use.

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?

Although schema coverage is 100%, the description is crucial here. It defines the expected content and purpose of the `key` (empty=list) and the `auth_event` (must be a specific signed event), adding necessary operational context beyond the data types provided by 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 description clearly states the function (read/list) and the resource (encrypted memory entry). It distinguishes its dual purpose by specifying behavior when the key parameter is empty versus when it is provided.

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 is extremely explicit about prerequisites: the agent must prove the key using a specific NIP-98 event kind, including the required URI and time window. It also defines the full operational scope (read vs. list).

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

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

Beyond the annotations (readOnly, openWorld, not idempotent), the description discloses that the decision is signed, bound to the payment hash, logged, and valid for five minutes, plus the concrete reason vocabulary (pay_to_unknown, pay_to_sanctioned, pay_to_frozen_by_issuer, over_budget ...). That is real behavioral context an agent cannot infer from the schema, and it is consistent with readOnlyHint=true because the tool judges rather than pays.

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 trigger, then the inputs, then the output semantics and action mapping, with no filler sentences. The parenthetical reason-code list is the only slightly heavy element, but it earns its place by preloading the vocabulary the agent will see in the response.

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?

Output schema exists, so return shapes need not be spelled out; the description still covers the decision categories, the five-minute validity window, and the signature binding. For a three-parameter tool with full schema coverage, nothing an agent needs to invoke 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 100%, so the baseline is a 3. The description reiterates the parameters (url, the 402 payload, optional max_usd) and adds only marginal meaning, namely that an over-budget option is blocked. That is useful but does not substantially exceed what the schema already documents.

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: judge an x402 payment option and return allow/hold/block, with the trigger point ('right before you sign an x402 payment'). What it does is unmistakable. It stops short of naming a sibling such as lint_x402_endpoint or check_service to demarcate how it differs from endpoint-validation 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 timing rule ('call this right before you sign') and defines the downstream action for each verdict (allow: pay; hold: ask your operator first; block: do not pay), which is exactly the usage guidance an agent needs. It never states exclusion conditions or names an alternative tool for cases where this one is wrong.

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 readOnlyHint/openWorldHint, the description discloses the exact auth contract (NIP-98 kind 27235, u and method tags, 60-second freshness window) and warns that message text is untrusted data from another agent, a prompt-injection guard the annotations cannot express. It stops short of describing failure modes when the auth event is stale or malformed.

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

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

Three short sentences, front-loaded with the action, then the auth requirement, then the safety caveat, with no filler. Every clause carries operational 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 shape and the next_since/next_after_id cursors need not be restated, and the auth path is fully spelled out. The remaining gap is the absence of any pointer to send_mail as the counterpart or to what happens on auth rejection.

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 100%, so the baseline is 3, but the description adds real meaning to auth_event by specifying the event kind, required tags, HTTP method binding, and timestamp tolerance. The since/after_id pagination parameters are left to the schema, which documents them adequately.

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

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

The description names a specific verb and resource: 'Fetch gift wraps addressed to you' plus local unwrapping, which an agent can map to reading inbound mail and distinguish from send_mail. The only weakness is that 'gift wraps' is protocol jargon that requires NIP-59 knowledge to fully decode.

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: 'addressed to you' signals an inbox read, but the description never states when to call it versus siblings such as send_mail or check_agent, nor when not to call it. Pagination strategy is delegated entirely to the schema's since/after_id hints.

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 a non-read-only, idempotent, non-destructive, open-world write. The description adds substantial behavior beyond that: no API key required, on-chain verification that the tx paid a known payTo in USDC/USDT within 7 days, signature into a public log, and downstream effects on Trust Score plus an immediate recheck on failure. Minor gap: it doesn't state what a rejected or duplicate report returns, though an output schema exists.

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 core instruction and its prerequisites are front-loaded in the first sentence, followed by verification mechanics and consequences in a compact block. The closing line ('This is how agents learn which sellers deliver.') is motivational filler rather than operational guidance.

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

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

For a six-parameter write tool with annotations and an output schema, the description covers the prerequisites (post-payment, no key), the verification rules (known payTo, USDC/USDT, 7-day window), the cardinality constraint (one report per payment), and the consequences of reporting — nothing an agent needs in order 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 100%, so the schema already documents all six fields, and the description only reinforces the tx field mapping (PAYMENT-RESPONSE transaction) already stated in the schema. It adds the useful 7-day verification-window constraint but says nothing about preflight_id or result_sha256, so the baseline of 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 names a specific verb (report) and resource (payment outcome for an x402 endpoint) and enumerates the allowed outcomes, so the agent knows exactly what action is performed. It also implicitly separates itself from preflight_payment and check_service by scoping the call to 'after you paid'.

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?

Timing guidance is explicit and actionable: call this only 'after you paid an x402 endpoint on Base or Solana', and 'one report per payment'. It does not explicitly name sibling alternatives such as preflight_payment for the pre-payment case, leaving the before/after split partly implicit.

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

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

Adds substantial context beyond the annotations: the payload is unreadable by alalanet, the sender is hidden from the relay, and messages are retained 30 days. These are real behavioral traits an agent needs. It stops short of covering failure modes, rate limits, or how the claimed idempotency interacts with a one-time signing key.

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

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

Two tight sentences, front-loaded with the action and format, followed by the privacy and retention guarantees. No filler or redundant restatement of the title or schema.

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

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

Given a nested object parameter and an existing output schema, the description covers format requirements, confidentiality, and retention, which is most of what an agent needs. It does not address what happens if delivery fails or whether the recipient must already be known to the relay.

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

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

Schema coverage is 100% and the single 'event' parameter is documented, so baseline is 3. The description goes further by enumerating what the gift-wrap must contain: kind 1059, p tag set to recipient pubkey, NIP-44 encryption, one-time signing key, and NIP-13 proof of work of 16 bits.

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 ('Deliver') and a precisely specified resource ('a NIP-59 gift wrap (kind 1059...) to the recipient's mailbox'). It clearly implies the inverse of the sibling read_mail without naming it, so an agent can distinguish send from read, but there is no explicit sibling callout.

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: you call this to send an encrypted message to another agent's mailbox. There is no explicit when-to-use vs when-not guidance, no mention of the read_mail counterpart, and no note on prerequisites such as knowing the recipient's pubkey or checking the agent first with check_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?

Annotations already cover the safety profile (not read-only, idempotent, non-destructive, closed-world), and the description adds genuinely non-obvious behavior: keys younger than 7 days require NIP-13 proof of work of 16, kind 4202 payments are verified on chain against the service payTo, and the response returns the log inclusion. It does not say what happens on rejected or duplicate submissions, so 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?

The purpose is front-loaded in the first clause and every clause carries payload requirements rather than filler. It is dense and run-on, with per-kind tag lists packed into nested parentheticals that are harder to scan than a bulleted layout, but nothing is redundant.

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 an output schema exists, the description need not explain return values, though it helpfully notes the log inclusion is returned. It covers all supported kinds, tag semantics, and the proof-of-work edge case; only error/rejection behavior and guidance on unsupported kinds remain 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?

Schema coverage is 100% and the single parameter is a nested object, so the schema does the structural work. The description still adds real meaning the schema cannot express: which tag keys (d, x, r, p, e, status, tx, outcome) each kind requires, that kind 4200 content must be empty, and the allowed network/outcome value sets.

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 action ('submit one Nostr event signed by YOUR key') and then enumerates the exact event kinds accepted (30422 release, 0 passport, 4200 receipt, 4201 confirmation, 4202 purchase report). An agent knows precisely which payload shapes this tool accepts, which distinguishes it from invoice or discovery siblings.

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?

Each kind carries its own triggering condition, e.g. kind 4202 is for use 'after paying an x402 endpoint', and the signer is told to 'sign locally; never send keys'. What is missing is explicit routing away from siblings such as report_purchase or create_invoice, and any statement of which kinds are not accepted here.

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 cover the safety profile (non-destructive, idempotent), and the description adds real substance beyond them: the three monitored conditions, that alerts arrive as a POST to webhook_url, and that the payload is a signed, logged attestation. Plan quotas (20 Pro / 200 Team) are also disclosed. It does not say what happens if the quota is exhausted or whether watches expire.

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

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

A single dense sentence front-loads the plan requirement and then the watched resource, trigger conditions, and delivery mechanism. Every clause carries information; only the quota tail feels bolted on.

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 values need no explanation, and the description still covers triggers, delivery channel, payload trust (signed attestation), and per-plan limits. Nothing an agent needs in order to call this 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 100% and the schema already states 'give either id or url' and defines webhook_url as the alert receiver, so the description's 'by url or id' adds no new constraint. Baseline 3 is appropriate since the schema carries 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?

Names a specific verb and resource ('watch an x402 endpoint or MCP server') plus the triggering events (down, back up, payTo/network change), so an agent knows exactly what the tool creates. It stops short of naming the sibling it contrasts with (check_service, check_artifact for one-shot checks), leaving the differentiation implicit.

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?

'Paid plans:' signals an eligibility prerequisite, which is useful gating context. However, there is no explicit statement of when to choose this over check_service or check_artifact (a polling check vs. a persistent webhook subscription), so the agent must infer the alternative from the trigger-based framing.

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