402post

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

Annotations only cover safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=true); the description adds substantial behavioral detail beyond that — the 402 error-result contract, receipt location in _meta, the one-time edit key, the free-validation-before-charge guarantee, and the 503 not_selling stop condition. The only minor gap is that it doesn't spell out rate limits or full idempotency semantics for retries.

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?

Long and dense, but front-loaded with the essential publish/price facts and every sentence carries load-bearing information (payment flow, batch rules, injection warning). It could be broken into clearer steps for the two client paths, but there is little pure 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 15-parameter, nested, no-output-schema tool with a multi-step payment handshake, the description covers what is returned (listing URL and one-time edit key), what the 402 body contains, and how batch errors are reported. Nothing an agent needs to invoke it correctly appears to be 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, but the description adds cross-parameter semantics the schema does not: payment_signature and _meta["x402/payment"] must never both be sent, and listings must be sent alone rather than alongside single-listing fields. It also restates the batch pricing tiers and the all-or-none error behavior with per-index errors.

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 ("Publish a listing") with the price, duration, and payment rail ($0.10 USDC / 30 days / x402 on Base) in the first clause. It clearly separates itself from siblings by naming validate_post as the pre-flight step and referencing list_categories for slugs, so an agent can distinguish it from get_post/search_posts without opening a schema.

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

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

Gives explicit when/when-not guidance: call validate_post first, call without payment to receive the 402 requirements, and the two distinct client paths (x402 MCP client vs. any other client signing an EIP-3009 authorization). It also states the failure conditions (422 free refusal, 503 not_selling with a do-not-sign instruction) and the batch alternative.

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 readOnlyHint and openWorldHint; the description goes well beyond them by disclosing the 410-gone behavior for removed or >30-day-expired listings, the `body_untrusted` flag, the 'Free' cost profile, and an explicit prompt-injection warning about third-party listing text. That is exactly the extra behavioral context annotations cannot carry.

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

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

Three dense sentences with the core operation front-loaded and no filler; the safety warning and the 410 case are ordered after the identifier contract where they belong. The telegraphic phrasing ('Free.') is compact but slightly terse.

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 still characterizes the return payload (what the .json endpoint returns, the `body_untrusted` marker) and the failure mode (410 gone). For a single-parameter read tool, an agent has everything needed to call and interpret it.

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% and the sole parameter already documents the 26-character format with an example. The description repeats '26 characters' and adds the provenance hint, but contributes no new syntactic or constraint detail, 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?

States a specific verb and resource ('One listing by id') and pins the identifier contract to a 26-character id. It is clearly distinguishable from create_post, search_posts, and validate_post by naming the exact retrieval semantics (what GET /p/{id}.json returns).

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 clarifies where the id comes from ('as returned by create_post and search_posts'), which tells the agent this is the follow-up read step after a search or create. It does not explicitly state when to prefer this over search_posts for bulk retrieval, so it stops short of full when/when-not routing.

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=false, so the safety profile is covered. The description adds genuinely new context: the call is 'Free' (cost signal) and the payload includes live listing counts. It doesn't mention caching, rate limits, or how fresh the tree is, so it stops short of a 5.

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

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

Two sentences, front-loaded with what the tool is and followed by the routing instruction. The long field enumeration is dense but each item earns its place because there is no output schema to carry it. Slightly run-on, but no wasted 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 must carry the return-shape burden, and it does: it enumerates slugs, usage notes, exclusions, examples, attributes, and listing counts. For a parameterless read tool with annotations, nothing an agent needs 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?

The tool takes zero parameters and the schema coverage is 100%, so there is nothing for the description to disambiguate. Per the baseline for parameterless tools, a 4 is appropriate; the description's enumeration of return fields is output content, not parameter semantics.

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 exactly what the tool returns: the 402post category tree with each category/subcategory's slug, usage guidance, anti-use cases, examples, attributes, and live listing counts. That is a specific resource with concrete contents, and the reference to validate_post separates it from the sibling validation/creation 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 an explicit trigger ('Call it first') plus a conditional trigger tied to a named sibling ('when validate_post says a category or subcategory is unknown'). The agent knows both when to reach for it and which sibling signal routes it 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 only cover read-only/no-open-world, but the description adds matching semantics (every word must match, no operators), ordering (newest first), a hard result cap of 18, the shape of returned items, that the call is free, and a prompt-injection warning that listing text is third-party data to be treated as data, not instructions. That is substantial behavior disclosure beyond the structured fields.

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

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

Four short sentences, each earning its place: scope/limit, match semantics, result shape plus follow-up tool, and the safety note. The most decision-relevant facts (what it returns and the 18 cap) are front-loaded.

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

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

There is no output schema, yet the description still characterizes the return payload (summary and links per item) and the retrieval path for full records. Combined with the match semantics and cap, an agent has everything needed to call it correctly.

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

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

With a single parameter at 100% schema coverage the baseline is 3, but the description genuinely adds semantics the schema lacks: the query is an AND-of-all-words match with no operator support, and any language is accepted. This tells the agent how to phrase queries rather than just what the field is.

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 (full-text search over live listings) and immediately delimits the result set with ordering and a hard cap of 18. It also distinguishes itself from the sibling get_post by noting that results are summaries/links and that the full listing must be fetched elsewhere.

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?

Clearly routes the agent: search here for summaries, then call get_post to retrieve a complete listing. It does not state when not to search (e.g., browsing via list_categories), so it stops short of full when/when-not coverage.

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 (readOnlyHint=true, openWorldHint=false). The description adds genuinely useful behavior: results are *candidates* rather than a single answer, each includes a ready-to-paste `location` object, and the call is Free. It doesn't state result limits or ordering, keeping it short of a 5.

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

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

Three short sentences, front-loaded with purpose, then return shape, then the optional narrowing parameter. Nothing is padded or 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?

With no output schema, the description correctly carries the return-value burden by explaining that candidates come back with a usable `location` object. Only ranking/tie-breaking or maximum-candidate behavior is left unspecified, a minor gap for a simple lookup.

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 the ISO alpha-2 format and adds that `country` 'narrows the search', which is a mild semantic gain over the schema's own wording, but it offers no new detail about matching behavior.

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

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

States a specific verb and resource ('find the place id of a city') plus the situational purpose ('for a listing's location'). This is clearly distinct from the sibling post/category tools, so an agent can route to 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?

The phrase 'for a listing's location' plus 'to paste into the listing' establishes when this tool is needed: resolving a location before creating/updating a listing. There are no explicit exclusions or named alternatives, but the context 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?

The readOnlyHint and idempotentHint annotations cover the non-mutating, repeatable nature, but the description adds critical context the annotations do not: no storage, no charge, error reporting granularity (every problem at once by field), batch atomicity ('one bad listing refuses the whole batch for free'), and an explicit security warning treating listing text as third-party data rather than instructions. It stops short of explaining output format or exact error payload shape, so 4 is warranted.

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

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

The description is front-loaded with the core purpose and then layers conditionals efficiently. It is dense but none of the sentences are idle — each addresses a distinct concern (same args as create_post, payer check, batch mode, security warning). Slightly long, but every clause earns its keep.

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 15-parameter validation tool with nested objects and no output schema, the description covers what an agent needs: the no-store/no-charge guarantees, required fields for a single listing, the batch alternative with limits and pricing, the optional payer for pre-sign checks, and a prompt-injection warning. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already defines all 15 parameters in detail (e.g., body length limits, payer wallet format, location structure, attributes, batch pricing). The description reinforces key semantics — payer is optional and adds payment-cap/duplicate checks, listings must be sent alone — which adds usable signal beyond the schema. That extra routing and optional-payer context lifts it above the baseline 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 opens with a specific verb and resource — 'Dry run of a listing' — and distinguishes itself from the write sibling by stating 'Nothing is stored and nothing is charged.' It also contrasts directly with create_post ('Send exactly the arguments you will send to create_post'), making its role unmistakable among the sibling tools.

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

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

It gives explicit when-to-use guidance: before signing, to learn if the daily cap or a duplicate would refuse the request, and exactly how to invoke it — send the same arguments as create_post, add 'payer' for payment pre-checks, or send 'listings' for a batch. The alternative write tool is named, and the batch condition (1-15, one payment, all-or-none) is stated.

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