P0: agent memory and utilities

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

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses that this returns a paid x402 request rather than the data itself, that the caller must invoke the URL with an x402 or MPP client, and that it costs $0.001 per call with validation before charging. These are exactly the non-obvious traits an agent needs, though absence-of-key behavior is unstated.

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

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

The purpose is front-loaded, but the middle sentences are dense and use 'Returns' twice for two different things (the value vs. the payment request), which reads ambiguously. The schema-link clause is low-value padding relative to the surrounding content.

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, the description responsibly characterizes the return payload (text, parsed JSON, size) and the two-step paid retrieval flow. The main gap is the not-found / missing-key outcome, which an agent would need to handle 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 single key parameter is fully documented with its pattern and length constraints in the schema. The description adds no meaning beyond the schema for the key itself, 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 states a concrete verb and resource: retrieve a value previously stored via /kv/put, returning text, parsed JSON, and size. Naming /kv/put distinguishes it from sibling kv_put/kv_list, though the pivot into x402 payment mechanics dilutes the opening a bit.

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 'Use when an agent needs a value it stored earlier with /kv/put' gives a clear trigger and implicitly excludes keys never written. However, it never mentions kv_list as the alternative for enumerating keys, nor what to do when the key is unknown.

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

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

Annotations already declare readOnly/idempotent/non-destructive/open-world, so the bar is lower, yet the description adds genuinely non-obvious behavior: the tool returns a paid x402 request document rather than the data, the agent must call the returned URL with an x402 or MPP client, cost is $0.001 per call, and bad input is refused before any charge. That two-step payment protocol is the single most important thing an agent must know and it is disclosed. It stops short of describing the response envelope or pagination 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?

Front-loaded with the trigger condition, then scope, then the payment/invocation protocol, in two dense sentences with no filler. The phrase 'Returns the exact paid x402 request for your input' is slightly awkward and could be tighter, which keeps it off a 5.

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-optional-parameter read tool with no output schema, the description covers the scope, the returned entry fields, the price, the validation-before-charge guarantee, and the otherwise-invisible fact that a second HTTP call is required to obtain data. Little 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 3. The description restates 'up to 100 keys' and 'optionally under prefix', which the schema already conveys via maximum: 100 and the prefix property; it adds nothing about cursor semantics or default limit, so it does not exceed 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?

States a specific verb and resource ('lists up to 100 keys ... optionally under prefix') and scopes it to 'the namespace of the paying wallet with size, stored_at and expires_at'. This is clearly distinguishable from siblings kv_get (single-key read) and kv_put (write) without opening their schemas.

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?

Opens with an explicit trigger: 'Use when an agent needs to see what it has stored', which is the right condition and implicitly excludes the single-key case handled by kv_get. It gives no explicit when-not guidance or named alternative, which keeps it below a 5.

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

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

Adds substantial behavior beyond the annotations: 8 KB value cap, private per-paying-wallet namespace, $0.001 per call, endpoint POST /kv/put, the two-step flow (this tool returns the paid x402 request; the caller POSTs it), and the guarantee that bad input is rejected before charge. There is mild tension with readOnlyHint=true since the description's 'store value' implies a write, but the description does explain that the mutation only happens when the returned request is POSTed, so it is clarified rather than contradicted. Overwrite semantics for an existing key are left implicit (inferred only from idempotentHint).

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-loads the 'Use when' condition and keeps everything to two sentences with no filler. The second sentence is dense and run-on, packing pricing, endpoint, schema link, and client requirements into one chain, but each clause carries real 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?

For a tool with no output schema, the description does the necessary work of explaining exactly what comes back (the exact paid x402 request plus a schema link) and how to consume it. Pricing, size limit, and pre-charge validation are all covered; only overwrite/expiry semantics are slightly under-explained.

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 defines key pattern, value types, and ttl defaults/limits; the description only restates the 8 KB value cap. TTL/expiry behavior and the consequence of key collisions are not elaborated in the description, 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 concrete action and resource: store a text or JSON value (up to 8 KB) under a key in a private, wallet-scoped namespace. This clearly positions it against kv_get/kv_list by implication (write vs. read/list), though it never names those siblings explicitly, which is the only thing separating it from 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?

Opens with an explicit conditioning clause: 'Use when an agent needs memory between runs without an account,' which gives a clear triggering context. It does not spell out when-not-to-use or name kv_get/kv_list as alternatives, so the agent must infer the complement from the sibling 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?

Annotations already declare read-only/idempotent/non-destructive, yet the description adds what they cannot: the $0.001 per-call price, that the default return value is a paid x402 request rather than the data, that a P0 bearer key changes the behavior to an auto-paid call with price deduction, and that invalid input is rejected before any charge. That is exactly the extra context an agent needs to avoid a surprise charge.

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?

Single paragraph, front-loaded with the 'Use when' trigger followed by output behavior, pricing, and auth. It is dense and slightly run-on, but nearly every clause (price, payment path, schema link, pre-charge validation) carries distinct operational value.

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 a dual payment/execution mode and no output schema, the description covers the return shape in both modes, cost, auth header format, key purchase URL, and error-before-charge behavior. An agent has everything needed to decide whether to call it and how to interpret the response.

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 all seven parameters are already documented in structured fields. The description restates the same parameters (n in [min,max], choices, unique, round) and adds only the 'choices=a,b,c' comma format hint, which is marginal beyond the schema. 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 names a specific verb and resource ('publicly verifiable random numbers: n integers in [min,max] ... a pick from choices=a,b,c or a unique draw') and names the underlying mechanism (drand / League of Entropy beacon round). No sibling tool produces randomness, so the agent can route here unambiguously.

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 when you need publicly verifiable random numbers' sets the trigger condition clearly, and the two execution paths (no key = returns the paid x402 request URL; P0 key = tool makes the paid call itself) are spelled out. It does not name any alternative among siblings, but none exists in the list, so the gap is minor.

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

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

Annotations already cover read-only, idempotent, open-world and non-destructive, so the description correctly focuses on things they cannot express: a $0.001 per-call cost, validation-before-billing, the Authorization: Bearer p0k_ key requirement, and the fact that the non-key path returns a request object rather than data. That is substantial context beyond structured fields. It stops short of describing the response payload shape in the keyed path.

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 correctly with the trigger clause, but it is a single dense paragraph that mixes time semantics, payment pricing, a key-purchase URL, and a schema link. The embedded purchase URL and the repetition of "paid x402 request" wording could be trimmed without losing meaning.

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 dual-mode paid utility with no output schema, the description covers pricing, auth, validation behavior, and roughly what each mode returns. Siblings are all unrelated utilities, so no routing detail is needed. Only a short sketch of the returned time payload would make it fully self-sufficient.

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 each parameter already documents its format, so the schema does the heavy lifting. The description only restates that tz takes up to 10 comma-separated zones, repeating the schema, and adds no detail about how at/to interact with tz. 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?

"Use when you need the current UTC time from a server clock, the local time, UTC offset and DST flag in up to 10 IANA time zones" names a concrete verb and resource, and no sibling tool overlaps. The purpose is clear, but the paragraph spends more words on x402 payment plumbing than on what the tool returns, which dilutes the opening statement.

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 an explicit trigger ("Use when you need...") and explains the two invocation modes: without a key it returns the payable request URL, with a P0 key it performs the paid call itself. It also states bad input is refused before any charge, which is useful pre-call guidance. It never explicitly says when to prefer this over computing time locally or which mode an agent should default to.

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

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

Annotations only cover the safe-read profile (readOnlyHint, idempotentHint, openWorldHint, non-destructive), and the description adds substantial context beyond them: the 64 KB cap, no external call, the $0.001 per-call price, and the crucial fact that by default it returns a paid x402 request rather than the data itself unless a P0 bearer key is supplied. It also promises 'Bad input is refused before any charge', which pre-empts the main fear an agent has about a paid endpoint.

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 correctly: the capability sentence comes first, then cost/transport, then the auth exception, then the validation guarantee. The middle sentence is a long run-on that packs the return value, price, schema link, and client instructions into one breath, which costs some readability but 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?

For a three-parameter utility with no output schema, the description covers limit, cost, transport, auth, failure behavior, and return shape well enough to call correctly. The minor gap is that in P0-key mode it doesn't say what the returned data payload looks like, but the schema link mitigates that.

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 all three parameters (input, action enum, url_safe) are already fully documented and the description mostly restates them in prose. The only added meaning is that the 64 KB ceiling matches the input maxLength and that decode yields hex when the bytes are not valid UTF-8, which is output behavior rather than parameter guidance. 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 and resource pair in both directions: 'encode UTF-8 text to base64 (standard or url_safe) or decode base64 back to text', with the non-UTF-8 hex fallback named. It is immediately distinguishable from siblings like util_hash, util_jwt_decode, or util_json_validate, so an agent can pick it without inspecting 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?

'Use when you need base64 in or out' is an explicit trigger condition, and the description spells out the two invocation paths (call the returned x402/MPP URL yourself, or hold a P0 key and let the tool make the paid call). It never names a sibling alternative or a when-not condition, but for a pure utility the context is clear enough to act on.

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

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

Annotations only declare readOnly/idempotent/openWorld, so the description carries the real behavioral burden and does: it discloses the x402 payment model, the $0.001 per-call price, the GET /util/hash endpoint, the P0 bearer-key path that makes the call server-side, and critically that bad input is refused before any charge. That pricing and pre-charge validation detail is exactly the context an agent needs before invoking a paid 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 triggering condition and core capability are front-loaded, and every clause carries information (algorithms, size cap, payment path, key header). It is nevertheless a single run-on sentence that packs the key-purchase URL inline, which is dense enough to slow parsing of the two invocation modes.

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, and the description covers both the unpaid mode (returns an x402 request to replay) and the keyed mode (returns the actual digest), plus price and validation behavior, which is enough to call it correctly. The return payload shape in the unpaid mode remains slightly ambiguous in how it is phrased, keeping it just below a 5.

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 all three parameters are already documented, including the enum for encoding and the comma-list semantics for algo. The description restates the algorithm and encoding options and adds the 64 KB bound (already implied by maxLength), so it adds little meaning beyond the schema; 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 states a precise verb and resource: compute a checksum/digest of a string, with the supported algorithms (sha256 default, sha1, sha384, sha512, md5) and the input encodings (utf8, hex, base64). It is distinguishable from adjacent siblings such as util_base64 or util_uuid because the hashing domain is stated 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?

"Use when you need a checksum or digest of a string" gives a clear triggering condition, and the description scopes usage with the 64 KB limit and the "no external call" / paid-call distinction. It stops short of naming when-not to use it or pointing at an alternative sibling, so it is clear context rather than full 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?

Annotations only declare it read-only, idempotent, open-world and non-destructive. The description goes well beyond that by disclosing the two operating modes (return a paid x402 request URL vs. execute the call itself with a P0 bearer key), the exact price ($0.001 per call, deducted from the key balance), the endpoint (GET /util/ip), and the charge-safety guarantee that 'bad input is refused before any charge' — a genuinely useful behavioral fact for an agent deciding whether to spend.

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 triggering condition is front-loaded and the sentences are information-dense, with no filler. It loses a point because a long buy-keys URL and two pricing/auth mechanics are packed into a single run-on sentence, which makes the paid-vs-free decision harder to scan 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?

For a zero-parameter lookup with no output schema, the definition covers everything an agent needs: what data comes back, what the call costs, the endpoint and schema link, the authentication path including where to purchase a key, and the guarantee that invalid calls are not billed. Nothing material about invoking it is 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?

There are zero input parameters, so the baseline is 4 and there is nothing for the description to disambiguate. It correctly implies no input is needed beyond optional auth, and the mention of 'bad input' does not conflict with the empty schema since that refers to malformed URL invocation rather than tool arguments.

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 resource and scope: 'its public IP plus the country, region, city, ASN, AS organization,' framed as how the agent 'is seen from outside.' That framing cleanly separates it from the other util_* siblings (base64, hash, uuid, jwt_decode, json_validate), which are local transformations rather than network egress lookups.

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 opening clause 'Use when an agent needs to know how it is seen from outside' gives a concrete triggering condition rather than a vague one. It does not name an alternative tool or state when-not-to-use it, so it falls short of a 5, but the context is clear enough that an agent can decide without opening the schema.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds meaningful context beyond them: the $0.001 per-call price, that it returns a prebuilt x402 request rather than the result, and that bad input is refused before any charge. The auth mechanism (Authorization: Bearer p0k_…) and key-purchase URL are also disclosed. It stops short of describing what a successful validation result actually looks like.

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 usage condition is correctly front-loaded, but the description then becomes a dense run-on covering payment flow, URL, price, error behavior, key acquisition, and dual-mode operation in a single block. The 'call that URL with an x402 or MPP client to get the data' clause is partially redundant with the preceding sentence.

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

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

For a two-parameter, read-only tool with no output schema, the description covers cost, access prerequisites, no-charge-on-invalid-input, and the two invocation paths. The main omission is the shape of the returned validation outcome (valid flag vs. list of schema errors), which the absent output schema would otherwise have supplied.

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 both parameters are already documented in the schema, including the note that an object in a POST body is accepted. The description adds no extra meaning about the 'json' or 'schema' inputs, so the baseline 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 and resource: 'validates json against a JSON Schema subset'. That is unambiguous and distinguishable from siblings like util_hash or util_jwt_decode. It never explicitly says how it differs from other util_* tools, but the resource noun is distinct enough that an agent can route on it.

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 triggering condition: 'Use when you must check that a JSON document fits a schema before acting on it'. It also distinguishes the two operating modes (no key = returns a paid request URL, P0 key = performs the paid call and returns data). No alternative tool is named, which is the only gap.

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

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

Annotations already declare readOnly, idempotent, non-destructive, openWorld, so safety is covered. The description adds genuinely non-obvious behavior: a listed price ($0.001/call), that bad input is rejected before charging, and that supplying a P0 bearer key makes the tool perform the paid call itself. The defect is that it never clarifies which of the two modes actually runs by default, leaving a real ambiguity about what the call does.

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 and returned fields are front-loaded, which is good, but the second half crams in pricing, a documentation link, an MPP/x402 client instruction, an access-key purchase URL, and a fallback mode. The buy-keys URL and payment plumbing are bulky and partly promotional relative to the single decode operation.

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 carries the return-value burden, and it does name the meaningful fields (header, payload, alg, kid, normalized times, expired flag). What is missing is the exact response envelope and what happens to the signature — whether it is validated, merely echoed, or omitted.

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 one parameter with 100% schema coverage ('JWT header.payload.signature', 65536 max length), so the schema already does the documentation work. The description contributes only the implied framing that no verification key is needed and that malformed tokens are cheaply rejected, which is marginal added meaning over 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?

States a specific verb and resource ('inspect a JWT without a key') and enumerates what comes back: decoded header and payload, alg, kid, iat/nbf/exp as ISO times, and expired-now status. This is clearly distinguishable from siblings like util_base64, util_hash, and util_json_validate, which do not decode tokens.

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 opening clause gives an explicit trigger condition ('when you need to inspect a JWT without a key') and the body explains the two invocation modes: raw x402 request vs. P0-key auto-call. It does not name an alternative tool or state when not to use it, so it stops short of the 5 bar.

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 it discloses cost ($0.001 per call), the auth requirement (Authorization: Bearer p0k_… with a purchase URL), the performance profile (edge-generated, crypto randomness, no external call, under 100 ms), and the charge-safety guarantee (bad input refused before any charge). It also explains the two return paths — a replayable x402/MPP request versus the data itself when keyed — which the readOnly/idempotent annotations do not convey.

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 is front-loaded and most content earns its place, but the definition is one long run-on sentence bundling performance marketing ('Cloudflare's edge with crypto randomness'), pricing, a full purchase URL, and a two-mode invocation model. The unkeyed-vs-keyed behavior would be far clearer as separate sentences.

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 only two optional parameters and no output schema, the definition covers what an agent needs: valid input range, the returned artifact in each mode, and the key requirement for direct data return. The one residual gap is that the shape of the returned x402 request object is only referenced via a schema link rather than described.

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 already carry descriptions, defaults, bounds (1-100) and an enum (4/7). The description restates 'n (1-100) random v4 or time-sortable v7' but adds no syntax, format or edge-case 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 states a specific verb and resource — generating fresh UUIDs — and pins down the shape (n of 1-100, v4 random or v7 time-sortable). It does not explicitly name a sibling (e.g. util_hash or util_base64) to differentiate from, 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?

'Use when you need fresh UUIDs' gives a clear trigger condition, and the description spells out two invocation modes: without a key you get a paid x402 request to replay, with a P0 key the tool makes the paid call itself. It gives no explicit when-not or alternative-tool guidance, but the context for use is unambiguous.

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

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

Annotations already declare readOnly, openWorld, idempotent and non-destructive, and the description adds genuinely new behavior beyond them: the $0.001 per-call charge, the currency options (USDC or USDT0 on Arbitrum), and the fact that invalid input is rejected before any charge. It omits how errors or partial payments surface, so it falls just short of full transparency.

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 purpose and the payment cost, then the return value and the follow-up URL. It is dense but has a few redundant re-statements of price and endpoint, which slightly holds it back from a 5.

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-parameter, no-output-schema tool, the description covers cost, currency, endpoint, return value and input validation. The main remaining gap is that it doesn't fully explain the returned URL or schema-link workflow, but it is otherwise complete for its complexity.

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 and the schema is empty, so the baseline is high. The description adds relevant meaning by explaining what the caller supplies outside the schema: which network to choose from 'accepts' and the payment currency.

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: it pays a tiny USDC fee and returns the decoded payment payload the server received, and it names the concrete endpoint (GET /x402-echo). It is clearly distinguishable from siblings like x402_ping and x402_test_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?

It states the use case ('Use for debugging an x402 client') and tells the caller to hit the returned URL with an x402 or MPP client, and that bad input is refused before any charge. It doesn't explicitly say when to prefer it over x402_ping or x402_test_purchase, so sibling routing is left 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?

The description says the tool 'pay[s] and settle[s] a real payment' and is '$0.001 per call', while the annotations declare readOnlyHint=true and idempotentHint=true. A real charge and settlement changes wallet and ledger state and costs money on every invocation, which directly contradicts the declared read-only and idempotent safety profile. The description is otherwise informative about price, bad-input refusal, and the return shape, but this is a contradiction between the description and the annotations.

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

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

The first clause usefully front-loads the purpose and price. The middle sentence, however, mixes three ideas in one run-on ('returns the exact paid x402 request', the GET path and price again, and a schema link), and 'call that URL with an x402 or MPP client to get the data' is unclear about whether the URL refers to this tool's endpoint or the schema link.

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 covers cost, endpoint, and the guarantee that bad input is refused before any charge, which is valuable given that there is no output schema. It does not explain what 'accepts' contains beyond naming networks, how payment challenge and settlement is negotiated, or how failures after charging are surfaced. These are the key gaps for a payment tool with no return schema and no params.

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 zero parameters, so the baseline would be 4. However, the description refers to 'the exact paid x402 request for your input' and 'Bad input is refused before any charge', yet the schema accepts no input at all; that is an unresolved mismatch that leaves the agent unsure whether input exists.

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 verb and resource: test that an x402 client 'can pay and settle a real payment end to end' at $0.001, naming the endpoint (GET /x402-ping) and price. It does not, however, distinguish itself from the x402_echo or x402_test_purchase siblings, so an agent cannot route between the three from this text alone.

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

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

It gives a clear triggering condition: use this tool when you need to verify payment and settlement behavior end to end. It states no exclusions or alternatives, and siblings such as x402_echo (presumably unpaid) and x402_test_purchase (presumably a larger amount) are not mentioned, so the agent must infer which x402 test tool to call.

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

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

Annotations already declare readOnly, idempotent and non-destructive, and the description adds real value on top: the $0.001 per-call price, the two-step flow (return the request, then call that URL with an x402/MPP client), and that invalid input is rejected before any charge. The remaining wrinkle is that it is not entirely unambiguous whether invoking this tool itself incurs the $0.001 or only the returned URL does, which slightly muddies the cost picture for a cautious agent.

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 content is packed into one long, comma-spliced sentence that repeats itself ("Use when you test…" followed by "a test target for x402/MPP clients, use it in your integration tests"). The key facts are present but not front-loaded or broken into scannable clauses.

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, the description must carry the return story, and it only says it returns "the exact paid x402 request" plus a schema link. That is enough to know a follow-up HTTP call is required, but the agent gets no sense of what the returned payload contains or what the free dry-mode response 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?

Schema coverage is 100% and both parameters (dry, msg) carry their own descriptions, so the schema does the heavy lifting. The tool description adds nothing about either parameter; the documented dry=1 free-rail listing and the msg echo behavior are only visible 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 description states a concrete verb and resource: it is a test target that returns the exact paid x402 request for a given input, hitting GET /x402/test. That is enough for an agent to tell it apart from the real purchase siblings (buy_brandwatch, list_paid_data_products), although it never names those alternatives 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?

"Use when you test an x402 or MPP client, wallet, SDK, facilitator or CI" gives a clear audience and condition, and "use it in your integration tests" reinforces it. There is no explicit when-not statement, but the test-target framing makes non-use for production data implicit.

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