402post

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

With annotations (destructive, non-idempotent, open-world) already flagging mutation risk, the description still adds a lot: charges nothing without payment, 402 body shape, edit key shown ONCE (store it), 422/503 semantics, and a prompt-injection warning to treat listing text as data. Doesn't spell out rate limits or whether published listings are editable/removable later, but covers the essential 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 core action and price, then the payment path, edge cases, and the injection caveat. It is dense and long, but nearly every clause carries actionable information; a slightly tighter arger would push it to 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 15-parameter, nested, payment-gated, no-output-schema tool, the description explains how to obtain the payment requirements, how to sign and retry, the return values (listing URL + edit key), and batch/error behavior. An agent has what it needs to call 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% (baseline 3), but the description adds relational meaning the schema alone lacks: payment_signature is 'the value you would send in PAYMENT-SIGNATURE' and 'never both' with _meta x402/payment, plus the batching/payment math for listings. It clarifies cross-parameter constraints, though individual field semantics are left mostly to the rich 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+resource (publish a listing), plus price ($0.03 USDC/30 days) and the x402-on-Base payment mechanism in the first sentence. It distinguishes itself from validate_post and get_post by naming them and describing the write-only publishing flow.

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?

Explicit routing: 'use validate_post first' for validation, 'pass listings instead' for batching, the 503 not_selling condition ('you must not sign'), and the 422 free-refusal cases. It tells the agent what to do on each outcome rather than leaving it to inference.

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?

Goes well beyond the annotations: it discloses whole-field replacement semantics (resend the full contact object), that untouched fields are preserved, that the new text re-passes the same validation gate, the exact error codes (422 immutable / 422 by field / 404 for wrong id or key), and the success payload (changed, listing links, edited_at). The destructiveHint=true annotation is corroborated rather than contradicted — each sent field overwrites the stored one — and the 'removal is not a tool' line correctly prevents the agent from assuming a delete capability.

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?

Almost every sentence carries load — immutable fields, replacement semantics, error codes, return shape, delete workaround — and the purpose is front-loaded. It is delivered as one dense run-on paragraph with parenthetical asides, which costs a little scannability for an agent parsing constraints.

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 compensates by stating what comes back (changed, listing links, edited_at) and the user-visible effect (the listing page shows the last edit date). For an 8-parameter mutation with nested objects, the immutable-field list, partial-update rule, validation behavior and error codes leave nothing an agent needs for a correct call.

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 genuinely non-obvious semantics the schema does not carry: only the fields you send are touched, and each is replaced wholesale rather than merged, with the contact object called out specifically. It also enumerates the editable field set as a whole, which helps the agent decide what may be sent.

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?

Opens with a specific verb+resource and scope ('Change a live listing of yours'), then anchors it to the exact API equivalent (PATCH /v1/posts/{id} with X-Post-Key). It also distinguishes itself from create_post by naming it as the path for changing locked fields, so the agent can tell the two apart 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-to-use (you hold the edit key from create_post), when-not (category, subcategory, intent, location, lang, external_ref, duration_days are immutable — publish a new listing instead), and an alternative channel for a case no sibling covers (deletion must be done via DELETE over HTTP, final and not refunded).

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 (readOnly, idempotent, closed-world), and the description adds genuinely new behavior: the 410 response for removed/expired listings, the body_untrusted marker, that the call is free, and that likes are per-address-per-day and not a ranking signal.

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 resource and its identifiers are front-loaded and there is almost no filler, though the sentence is dense and the likes explanation sits mid-paragraph rather than being clearly separated as response interpretation 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?

With a single fully documented parameter, no output schema, and full annotation coverage, the description fills the remaining gaps: what the response represents, the gone/expired error state, the meaning of likes, and the untrusted-content handling instruction.

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 itself documents the 26-character id with an example. The description restates the same 26-character fact and adds only the provenance of the id, so it does not meaningfully extend what the schema already provides.

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

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

The description names the specific action and resource ('One listing by id') and anchors it to a concrete endpoint contract ('what GET /p/{id}.json returns'). Referencing create_post and search_posts as the producers of the id implicitly distinguishes this read-one tool from the create and search 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?

It establishes the precondition (you need a 26-char id, obtained from create_post or search_posts) and the failure case (410 for removed or >30-day-expired listings). There is no explicit 'use search_posts instead if you only have a query' exclusion, so routing guidance is clear but not fully enumerated.

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, closed-world, so the safety profile is covered. The description adds genuinely new context: the call is free, it is the intended first call, and it details the payload fields an agent will receive. It does not mention the tree's size or response shape beyond field names, which keeps it at a 4.

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: the first front-loads what comes back, the second front-loads when to call. The field enumeration is dense but each item tells an agent what it can extract, so nothing is wasted.

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

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

There is no output schema, so the description carries the return-value burden and does so by naming every field. Combined with the call-first guidance and the validate_post fallback, an agent has everything needed to invoke 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?

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. It correctly implies no input is needed by framing the call as unconditional ('call it first').

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 the resource precisely (the 402post category tree) and enumerates exactly what each node carries: slug, when to use it, what it is not for, examples, attributes, and live-listing counts. That level of specificity makes it unmistakable against siblings like get_post or search_posts.

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 both a default trigger ('call it first') and a conditional trigger ('when validate_post says a category or subcategory is unknown'), naming the sibling tool that produces that condition. No inference required.

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: result cap of 18, newest-first ordering, match semantics (every word must match, prefix matching for words of three or more letters, no operators), pagination via 'next', and that the tool is free. It also warns that listing text is third-party content to be treated as data, not instructions.

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 purpose and ordering, then pagination, then return shape and safety note. Every sentence carries actionable information with no filler.

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

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

There is no output schema, and the description compensates by explaining the return shape (summary and links per item, 'next' token for paging) and the cap of 18. Together with the safety note, it gives an agent everything needed to call and interpret the 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%, so the baseline is 3, but the description adds match semantics for 'query' (all words must match, prefix matching, no operators) that the schema does not convey. The 'after' and 'category' semantics largely restate the schema, which keeps it from a 5.

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') plus scope details (newest first, 18 per call, optional category). It also distinguishes itself from get_post by saying get_post fetches the whole listing while this returns summaries and links.

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?

Routes the agent clearly: use the returned 'next' as 'after' for older results, and use get_post when the full listing is needed. It stops short of explicit when-not-to-use guidance, such as browsing by category via list_categories instead of searching.

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, openWorld=false and non-destructive, so the safety profile is covered. The description adds genuinely new behavior: it returns a candidate list (not a single resolution) and each candidate is pre-shaped for pasting into a listing, plus it is free to call. Little is left undisclosed.

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 purpose and the return shape, then the optional filter and cost note. Every sentence carries information not found elsewhere.

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 does the necessary work of describing the return value (candidates with a ready `location` object), and both parameters are covered. It stops short of saying what happens on ambiguity or empty results, but an agent has enough 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?

Schema coverage is 100%, with both `q` (place name in any language) and `country` (ISO 3166-1 alpha-2) documented in the schema itself. The description only adds that `country` 'narrows the search', which is a marginal restatement rather than new syntax or precedence detail, so baseline 3 applies.

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

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

States a specific verb (find/suggest) and resource (place id for a city), and clarifies the intended consumer ('for a listing's location'). The return shape ('candidates, each with a ready `location` object') removes any ambiguity about what the tool produces.

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?

Clear context for when to use it — resolving a city to a place id before creating or updating a listing — and notes the optional country filter plus that the call is free. No exclusions or named alternatives, though the siblings (post/category tools) are unrelated, so little real ambiguity remains.

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 mark it as read-only, non-destructive, and idempotent. The description adds rich behavioral details: 'Nothing is stored and nothing is charged,' explains the return format (every problem at once, by field, with allowed values), batch errors include indices, and warns that listing text is third-party data not instructions. This exceeds annotation coverage.

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 key concept (dry run), then details behavior, usage, and ends with a security note. Every sentence contributes purpose; there is no filler or redundancy despite covering multiple aspects.

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 fully explains what is returned (errors by field with allowed values) and how batches report errors with indices. It also covers optional payer behavior and a security warning, leaving no critical gaps for a validation tool.

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 baseline is 3, but the description adds crucial parameter grouping: it lists the fields needed for a single listing (category, subcategory, intent, title, body, lang, location, contact) even though the schema marks zero required parameters. It also clarifies the listings array option (1-15) and payer usage. This meaningfully supplements 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 explicitly states it's a dry run of a listing, returns problems by field, stores nothing, and charges nothing. It distinguishes from create_post by instructing to send the same arguments for validation. This is a specific verb+resource with clear differentiation from 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?

It directly says to send exactly the arguments you will send to create_post, and explains the optional payer for cap/duplicate checks. The usage context (pre-validation) is unambiguous, and no alternatives are needed because it's the only validation tool among siblings.

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