CurlShip

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description goes well past that with commercial consequences an agent could not otherwise know: one-time payment, no refund on being outbid, current $51 minimum, and an always-dofollow link. That is precisely the kind of irreversible-cost disclosure a caller needs before invoking.

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?

Five short sentences, front-loaded with what the tool gets you, then cost, then prerequisite. Every clause carries a fact an agent needs; nothing is padded or repeated.

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 simple two-parameter transactional tool with no output schema, the description covers effect, price, refund policy, and precondition. It leaves open what a successful bid returns (current price, position, next minimum), which matters in a competitive auction, but no output schema exists to backfill 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 both parameters are already documented, and the description's "Omit amount_usd to bid $51" merely restates the schema's "Omit to bid the minimum (51)." No syntax, increment, or range detail is added 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 verb+resource pair ("bid" + "Featured spot") is explicit, and "It sits above every listing" pins down exactly what the placement is. It cleanly separates itself in spirit from the read-only sibling read_featured, though it never names that sibling.

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 prerequisite "The product must already be listed" gives a concrete precondition that determines whether the call is legal, and the $51 minimum sets the bidding context. It stops short of naming alternatives such as read_featured or x402_bid_featured, so there is no explicit when-not or sibling 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=false, destructiveHint=false, openWorldHint=true, so safety framing is partly covered. The description usefully adds the one-listing-per-domain constraint and that the new URL replaces the prior page, but says nothing about the required proof-of-ownership step or what happens to the old URL on failure.

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 short sentences, action first, constraint second — front-loaded and free of padding. The domain-rule sentence is terse to the point of being slightly cryptic, but it 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?

For a three-required-parameter mutation with no output schema and no parameter documentation, the description is thin. An agent still cannot tell what proof means, how ownership is verified, or what the response returns after the URL is changed.

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 0%, so the description must carry all parameter meaning, and it does not. It implies the url parameter but never explains listing_id or the required proof enum (email vs domain), which is the most consequential input to get right.

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?

"Point an existing listing at a new URL" gives a specific verb (point/repoint) and resource (existing listing's URL), which separates it from creation-oriented siblings like submit_listing. It doesn't explicitly name those siblings or state the contrast, so the differentiation is inferential 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 clause "One listing per root domain, so this is how a second page replaces the first" implies when to use it (when a new page should take over from an existing one on the same domain). It gives no explicit exclusions, no mention of when to use refresh_listing/submit_listing instead, and no prerequisites.

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=false, destructiveHint=true, and openWorldHint=true. The description adds useful flow context for refresh edits, but does not explain what is destructive, whether the operation is reversible, or what token/request_id authorization requirements apply.

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 two short sentences and front-loads the core action. It is concise overall, though the second sentence is somewhat cryptic without knowing the preview/confirm flow.

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 destructive mutation tool with no output schema and low schema description coverage. The description omits important context about token/request_id, what happens for URL changes/removals, and the consequences of applying an edit request.

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 only 33%, and the description mostly echoes the existing apply field wording ("apply digest from the preview"). It adds no meaning for token or request_id, leaving two required parameters undocumented.

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 clear verb and resource: "Apply an edit request." That is enough to distinguish it as the confirmation/application step, but it does not explicitly name or differentiate the sibling flows such as refresh_listing, change_listing_url, or remove_free_listing.

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 sentence "A refresh needs a second call with the apply digest from the preview" gives one concrete usage path. However, it does not state when to use this instead of alternatives or clearly restate that apply should be omitted for URL changes/removals, which appears only in 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?

The annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds meaningful behavioral detail beyond the annotations by explaining zero-filling, daily entry granularity, and the cumulative running total, though it does not discuss auth or rate limits.

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 compact and front-loaded, stating the core data first and then adding the zero-fill and entry-shape details. Every clause contributes useful information without repetition.

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, but the description adequately explains the return shape: one entry per calendar day, from the first listing to today, each containing added and cumulative running total. Combined with the fully documented single optional parameter, this is complete for a read-only stats 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 description coverage is 100%, so the range parameter's meaning and allowed values are already fully documented in the schema. The description does not add parameter-specific guidance beyond describing the default full-series shape, making the baseline score appropriate.

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 resource and scope: active listings added per UTC day, zero-filled, one entry per calendar day, with added and cumulative running total. It is clear what the tool returns, but it does not explicitly differentiate itself from sibling tools such as get_stats.

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 by the phrase 'the zero-filled series behind the public /stats page,' which suggests a reporting context. However, it gives no explicit when-to-use guidance, when-not-to-use guidance, or named alternatives among the 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?

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds meaningful context beyond that: one reading per UTC day, current value, last step vs most recent different reading, and growth since first reading.

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 core resource and then details the returned components. The single sentence is dense but every clause adds useful information, with little waste.

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 carries the return-value explanation and does so adequately: it lists the series, current value, last step, and growth. It could mention pagination or data limits, but for a no-param read-only history tool it is largely complete.

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 has zero parameters, so there is no parameter semantics to explain. Baseline is 4 for a no-parameter tool.

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 specific resource: Ahrefs Domain Rating history over time, tied to /stats#dr. It distinguishes itself from general stats siblings by naming DR specifically, though it doesn't explicitly contrast with get_stats or get_daily_stats.

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 by the DR-specific framing, but there is no explicit guidance on when to use this versus get_stats or get_daily_stats. No exclusions or alternative-routing instructions are provided.

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 safety is covered. The description adds almost nothing beyond the data points named: it doesn't say whether counts are totals or broken down by category/status, whether stats are scoped to the caller's own directory, or how fresh the Ahrefs DR value is.

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 short with no waste, but it is an incomplete sentence fragment rather than a front-loaded statement of action and scope. Brevity here comes at the cost of clarity.

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 and no parameters, the description is the only place to explain what 'counts' includes and how this differs from get_daily_stats/get_dr_history. It leaves both questions open, so an agent cannot confidently choose this tool over its near-duplicate siblings.

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 of 4 applies; there is no parameter semantics to explain.

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 is a noun fragment ('Listing counts and the Ahrefs Domain Rating') with no verb, so it only implies retrieval; the title 'Get directory stats' supplies the actual action. It does identify the two data points returned, which distinguishes it partially from siblings like get_daily_stats and get_dr_history.

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?

No guidance on when to use this versus the closely overlapping siblings get_daily_stats and get_dr_history, both of which appear to cover similar stat data. The agent must infer that this is the current snapshot tool and the others are time-series tools.

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 safety (readOnlyHint=true, openWorldHint=false). The description adds useful context about the return shape—hierarchical tree, per-category listing counts, group slugs, and promoted leaf categories—which helps an agent understand what data it will receive.

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 the core resource, and no wasted words. The second sentence adds an important relational note without bloating the description.

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 read-only tool with no output schema, the description sufficiently explains what is returned: a category tree with counts, slugs, and promoted leaves. It could clarify whether counts are total or active listings, but the essential contract is covered.

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

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

The tool has zero parameters, so the baseline score is 4. The description appropriately does not discuss parameters and focuses on the resource and its 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 clearly states the resource (category tree) and its structure: listing counts, group slugs, and promoted leaf categories. It distinguishes itself from all siblings, which are listing-level operations, by focusing on categories and explaining that listing category fields use these slugs.

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 by the statement that each listing's category field carries one of these slugs, but there is no explicit when-to-use guidance or mention of alternatives such as submit_listing. An agent can infer that this tool is for discovering category slugs, but the description does not spell out that workflow.

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

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

Annotations already declare readOnlyHint and openWorldHint=false, so the description adds real value on top: stable ordering ('same order as before'), default page sizes tied to query mode, and the shape of each returned record including the nullable category object. It stops short of stating total counts or what happens on an out-of-range offset.

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 behavior and defaults, then the parameters, then the return shape. Every clause carries information, though the parameter walkthrough is somewhat list-like and partly redundant with 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?

There is no output schema, so the description usefully covers return fields (created_at, category object with slug/name/group, null when unclassified). For a small read-only list tool with full schema coverage, the remaining gap (pagination totals, empty-result behavior) is minor.

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 five parameters. The description largely restates those definitions, adding only the slight nuance that category may be a group or a 'promoted leaf' and that q spans title, description, or URL.

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 resource and format ('Active listings as JSON') and the tool name supplies the verb. It is clearly distinct from the mutation siblings (submit_listing, upgrade_listing) and from stat tools, though it never explicitly differentiates itself from list_categories.

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 default case is stated precisely ('No query returns every listing'), which tells an agent when no parameters are needed, but there is no guidance on when to reach for this versus list_categories or get_stats, and no exclusions are given.

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 the returned fields, but does not disclose error cases, bid freshness, or auth/rate-limit behavior; with annotations, this is adequate but not rich.

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 one compact sentence with no filler and is front-loaded with the key question. Both returned data points are named efficiently.

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 read with annotations covering side effects, the main gap is return format since there is no output schema. The description names the returned values, which is sufficient for a simple lookup, though it could be more explicit about shape.

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 has zero parameters, so there is no parameter burden and the baseline is 4. The description correctly introduces no 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 the resource (the Featured spot) and the two data points returned (current holder and minimum bid), and the read-only framing distinguishes it from bid_featured. It does not explicitly name or route against sibling bid tools, so it falls short of 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?

No sentence says when to call this versus bid_featured or x402_bid_featured, nor any prerequisite such as checking the current bid before bidding. The read-only nature implies usage, but the description leaves the agent to infer it.

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 indicate this is not read-only, not destructive, and operates in an open world. The description adds a two-step preview-then-save flow, but the referenced apply parameter does not exist and the meaning of proof is left unexplained, making the behavioral disclosure incomplete and somewhat misleading.

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 short and front-loads the core purpose. The final sentence about confirm/apply is concise but confusing because apply is not an accepted parameter.

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 should explain what the preview returns and how proof is supplied. Instead it references an unsupported apply step and omits proof semantics, leaving the agent without enough information to complete the two-step operation reliably.

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 0%, so the description should compensate. It names listing_id and proof, but does not explain the proof enum values (email/domain), and it introduces a non-existent apply parameter, leaving key parameter semantics unclear.

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: re-read title, description, and image from the listed page. The operation is clear enough to distinguish from siblings like submit_listing or change_listing_url, but no sibling is named 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?

Provides procedural guidance for invocation: send listing_id and proof only, first confirm previews, then apply saves. It does not say when to use this tool versus alternatives like confirm_edit, and the apply step is not represented in 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 destructiveHint=true, readOnlyHint=false, and openWorldHint=true, so the safety profile is covered. The description adds useful refusal behavior for paid/Featured listings, but does not explain permissions, irreversibility, or what the response 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 description is short and front-loaded, with the core action stated first and the paid/Featured refusal stated last. The middle sentence is overly compressed and potentially misleading, keeping it from being fully clean.

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 destructive mutation with three required parameters, no output schema, and 0% schema description coverage, the description leaves out key parameter meaning and operational context. The refusal condition helps, but the definition is not complete enough for reliable invocation.

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 0%, so the description must compensate for three required parameters. It mentions remove true but omits listing_id and proof, and its phrase 'no url or email' is confusing against the required proof enum of email/domain.

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: taking a free listing off the directory. It also distinguishes the target from paid listings and the Featured holder, which are refused, so an agent can tell this is not a general listing-removal tool.

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

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

The description implies when to use it by saying only free listings can be removed and that paid listings or the Featured holder are refused. However, it does not name an alternative action for those refused cases or give broader when-to-use guidance.

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

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

Annotations only declare the safety profile (non-read-only, non-destructive, open-world), while the description adds overwrite semantics, the default fallback to ?ref=curlship, and the tier gate that causes refusal. It omits any mention of the required `proof` parameter or how ownership is verified, which is the main behavioral 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?

Three dense sentences with zero filler: capability, validation grammar, reset behavior, and eligibility all front-loaded in that order. The compact charset notation conveys a lot in few tokens.

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 3-required-parameter mutation with no output schema, the description covers the tracking map thoroughly but leaves `proof` — a required enum tied to authorization — undefined, so an agent may need to guess or call speculatively.

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 33% — only `tracking` is documented in the schema, and the description compensates well there by specifying allowed keys (ref or utm_*), count limit, charset, and value length. But `listing_id` and especially `proof` (enum email/domain) are left completely unexplained, so an agent cannot infer what proof value to send or why.

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 (set tracking params on a paid listing's outbound link) plus the eligibility tier (Bronze and up). No sibling tool touches tracking params, and the description makes the scope of the write unambiguous.

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 an explicit when-not condition ('Free listings are refused') and an explicit reset recipe ('Send {} to clear back to ?ref=curlship'). It does not name a sibling alternative for related URL work such as change_listing_url, but the usage context is otherwise clear.

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 (which only say it is not read-only and is open-world), the description discloses that the listing goes live immediately with no review step, a per-domain uniqueness constraint, and a specific rejected input value. What remains unstated is what happens on failure or what a successful response contains.

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, with the side effect (goes live immediately) placed right after the action and the constraints following. No filler and nothing redundant with 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?

For a three-parameter mutation with no output schema, the description covers the key risks: immediacy, the domain uniqueness rule, and one rejected value. It could go further on what the email is used for and what a successful submission returns, but the essential calling information is present.

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 33%: only tier carries a description, and url/email are bare strings. The description partially compensates by explaining that the placeholder URL is refused, but it says nothing about the email parameter's role or the URL format accepted, leaving a real gap for a required field.

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?

"List a product" names a concrete action and the resource being created, and "It goes live immediately" clarifies the outcome. It does not, however, distinguish this from the sibling x402_submit_listing or upgrade_listing, so an agent must infer which submission path applies.

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

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

The description gives real preconditions: one listing per root domain, and the documentation placeholder URL is refused. It never states when to choose this over x402_submit_listing or upgrade_listing, so the selection guidance is only implied.

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 indicate this is not read-only and is open-world. The description adds useful context that the result is a checkout URL rather than an immediate upgrade, but it does not clarify whether the listing changes immediately, whether payment is completed externally, or what authorization is required.

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 definition is a single efficient sentence with no filler. It is perhaps overly terse, but every word contributes and there is no structural waste.

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 an open-world, non-read-only checkout flow with no output schema and undocumented parameters, the description is under-specified. It should explain the 'url' parameter, the checkout/upgrade flow, and what the returned URL is for.

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 0%, so the description must explain the parameters. It does not clarify whether 'url' is the listing URL, an identifier, or a callback URL, and it adds no meaning to the tier enum beyond calling it a 'paid tier'.

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 identifies the resource and operation domain clearly: a checkout URL for a paid tier on an existing listing. 'Already exists' helps distinguish it from submission tools like submit_listing, though the phrasing leads with the return value ('Checkout URL') rather than the action.

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 'on a listing that already exists' gives an implied precondition and contrasts with listing creation, but the description does not explicitly say when to use this versus submit_listing, x402_submit_listing, or bid_featured, nor does it state required ownership or payment prerequisites.

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 declare readOnlyHint=false and openWorldHint=true, and the description goes beyond them by disclosing the actual state change: a free listing with the badge becomes dofollow. It does not describe the negative outcome (what happens if no badge is found) or the response, which keeps it below 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 short sentences, front-loaded with the action and followed by the consequence. No filler or restated metadata.

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 one-parameter mutation with no output schema, the description covers the action and its benefit but omits the failure path (badge absent, site unreachable) and says nothing about what the call returns, which the agent needs to interpret the outcome.

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 0% for the single url parameter, so the description must carry the meaning. "The listed site" does imply the url refers to an already-listed site rather than a listing ID and that a prior listing must exist, but no format, domain-vs-page, or required-state guidance is given.

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?

"Re-check the listed site for a link to curlship.com" gives a concrete verb (re-check) and resource (site membership/badge link) plus the downstream effect (free listing becomes dofollow). It is specific enough to distinguish from submit_listing or list_listings, though it does not explicitly differentiate itself from the similarly-named sibling refresh_listing.

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: call this after a listing is placed to confirm the badge and obtain the dofollow upgrade. There is no explicit when-not condition and no mention of the closest alternative, refresh_listing, leaving the agent to infer which of the two to invoke.

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=false and destructiveHint=true, so the description correctly reinforces the money-spending nature with 'settled on-chain with no checkout and no human in the loop' and the 402 handshake. It adds genuine protocol context beyond the annotations, but leaves open what happens to a losing or outbid bid (refund, escrow, irreversibility of the on-chain transfer) — a meaningful gap for a paid mutation.

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 distinguishing fact (USDC, on-chain, same auction as card bid) and then the mechanics, with no filler sentences. Minor redundancy: 'Omit amount_usd to bid $51' duplicates the schema's 'Omit to bid the minimum (51)'.

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 destructive, open-world payment tool with no output schema, the description covers the payment protocol, prerequisites, and minimum bid — enough to invoke correctly. What is missing is post-call behavior: confirmation of a successful bid and the consequence of being outbid, which matters given real funds move.

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 real semantics: it explains why payment_signature is omitted first (to receive the quote) and ties `url` to a precondition ('must already be listed'). The final sentence largely restates the amount_usd schema text, which caps it below 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 ('Bid on the Featured spot') and immediately scopes it against the sibling card-bid path ('the same auction as a card bid ... but settled on-chain'). An agent can distinguish x402_bid_featured from bid_featured without opening either 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 the exact two-call choreography (call without payment_signature for the 402 quote, sign accepts[0] as an EIP-3009 authorization, call again echoing it as `accepted`) plus prerequisites ('The product must already be listed') and a default behavior ('Omit amount_usd to bid $51'). This is explicit when-and-how guidance, not 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?

Well beyond the annotations: it discloses the 402 challenge/response protocol, the PAYMENT-REQUIRED header format (base64), EIP-3009 signing, on-chain settlement, and that the tier is granted in the same call that carries the signature. That is exactly the behavioral context an agent needs for a payment 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?

Dense but front-loaded and every clause carries real information about the payment flow. The quote/sign/pay sequence is a single long sentence, which is slightly heavy but warranted by the protocol complexity.

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 4-param payment tool with no output schema, it covers the full interaction loop including the no-signature 402 response body and header, and defers url/email validation to the free-submission rules. Nothing critical is left unexplained.

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 50%. The description richly explains payment_signature behavior (omit to get a quote, sign accepts[0], echo as accepted) and enumerates the valid tiers. It adds little for url and email beyond deferring to free-submission rules, so not 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+resource (buy a listing tier with USDC over x402) and names the exact tiers sold. It also contrasts against a free submission ('same URL and listing rules as a free submission'), so an agent can place it relative to submit_listing.

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 two-step calling procedure is spelled out explicitly (call without payment_signature to get the 402 quote, sign accepts[0], call again). What's missing is an explicit statement of when to choose this paid tool over submit_listing or upgrade_listing; it only implies it via 'same rules as a free submission'.

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