swop

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

Beyond the annotations, the description discloses important behavioral traits: the first call does not place the link, it returns a recommendation; the second call performs the placement; and the tool returns a viewUrl for previewing. This is meaningful context that annotations alone do not provide.

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 well-structured with a clear 'TWO STEPS' organization that front-loads the critical workflow. Every sentence contributes necessary operational detail, and the preview types and optional overrides are summarized 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?

Given the tool has 7 parameters, no output schema, and a nontrivial two-phase flow, the description is exceptionally complete. It covers the first-call recommendation, the second-call placement, layout options, override fields, and the returned viewUrl, leaving no major operational gap for an agent.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds workflow-level meaning by explaining when displayAs should be omitted versus set, how url is reused across both calls, and that overrides like title/buttonName/description/style apply to the infobar layout. This goes slightly beyond the schema's individual field descriptions.

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: 'Add a link to the linked account's SmartSite'. It also clarifies the smart-placement behavior and two-step nature, making it easy to distinguish from siblings like swop_remove_link and swop_update_my_smartsite.

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 an explicit two-step usage protocol: call with just the URL to receive placement recommendations, then call again with displayAs to place the link. It also tells the agent to show previews and ask the user which layout they want. It does not explicitly name alternatives or exclusions, but the workflow guidance is strong.

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 (not read-only, not open-world, non-destructive). The description adds substantial behavioral context the annotations cannot: prices in the request are rejected, shipping is auto-charged for physical goods, card rail only applies when card-enabled and all items physical, response shape (cardOffered:true, paymentRequest null until rail selection), the exact endpoints for card/crypto selection, and that settlement is automatic with no confirmation needed.

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 the alternative before diving into rails and response details. It is dense and long, but nearly every clause carries operational weight (required fields, rejection conditions, endpoints, polling). Slightly heavy for a single block of prose.

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 complex 7-param mutation tool with no output schema, the description compensates by describing the return values (paymentRequest solana: URL, cardOffered flag), the rail-selection flow, and the settlement/polling model with swop_get_checkout. An agent has everything needed to invoke and follow up 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 real meaning beyond the schema: prices must NOT be sent (a request price is rejected), buyer fields are hard-required for physical items, and offerCard only takes effect under specific conditions. Minor gap: it doesn't clarify selectedOptions or buyerPhone behavior beyond what the schema states.

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 ('creates a checkout for a cart') and pins the scope ('the linked account's OWN products'), so the agent immediately knows this is a seller-side checkout rather than a link generator. It explicitly names the sibling it is not (swop_get_product_link) for the single-shareable-link case.

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 ('take payment on the seller's own website... instead of being sent to Swop') and when-not ('For a single shareable link use swop_get_product_link instead'). It also lays out prerequisites: buyer name/email/address are required for physical items and the call is refused otherwise.

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 mark it as non-read-only, open-world, and non-destructive. The description adds substantial behavioral detail: posts are public, images are hosted, previews return previewId and hosted URLs, changes after preview are refused, each preview publishes at most once, and confirmation must follow user approval. These are critical traits not captured by annotations.

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

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

The description is dense but front-loaded: it opens with the purpose, then image constraints, then the two-step workflow and safety rule. Every sentence carries operational information; no runtime detail 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?

For a complex write tool with no output schema and no required parameters, the description explains the preview return shape (hosted URLs, previewId, posting identity) and the idempotent confirm behavior. It gives enough for an agent to call both steps correctly and avoid accidental publication.

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

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

Schema coverage is already 100%, so the baseline is 3. The description still adds useful constraints beyond the schema: max 5 MB per image, approximately 3 MB total for inline images, and the requirement to reuse the preview's hosted image URLs exactly on confirm.

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

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

Names a specific verb and resource ('Publish a PUBLIC post to the Swop feed') and scopes it to the linked account's SmartSite. It distinguishes the tool from siblings by contrasting its two-step preview/confirm flow with swop_send, so an agent can identify it as the feed-posting 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?

Gives a clear workflow: call without confirm to get a preview, show the user, then confirm with the same caption, smartsiteId, images, previewId, and confirm: true. It references swop_send as a similar pattern but does not explicitly state when to choose this over swop_send or other posting tools, so it falls short of full alternative 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 this is a non-readonly, non-destructive, non-open-world write. The description adds real behavioral context beyond them: no store setup, payment processor or verification is required, and settlement happens in USDC over x402. It does not cover irreversibility or authentication requirements, which keeps 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?

Front-loaded with the value proposition, then the alternative, then required fields, then the follow-up workflow. Every sentence carries information. The opening sentence is dense but not padded.

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

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

For a 15-parameter creation tool with no output schema and no nested objects, the description supplies the workflow context an agent needs (required fields, user-confirmation step, next calls) without explaining return values, which is correct given no output schema exists. It does not address failure modes or idempotency, a minor gap.

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 documents all 15 parameters including enums and constraints. The description only re-emphasizes that name, description and image are backend-required — information the schema's `required` array already conveys — so it adds little semantic value over the structured data. 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+resource ("creates a product") and immediately scopes it to the two channels it serves (SmartSite buyers and AI agents over x402). It explicitly names the sibling swop_update_product as the not-this tool, so an agent can distinguish it 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 both an exclusion ("To change an existing product use swop_update_product instead") and a prerequisite procedure ("Confirm name and price with the user before creating"), plus the correct downstream follow-ups (swop_feature_product, swop_get_product_link). This is a complete routing story.

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 non-obvious behavior beyond annotations: each call ADDS a tile and never replaces existing ones (idempotency warning), duplicates are possible, and the product must belong to the linked account. Annotations only say readOnlyHint=false, openWorldHint=false, destructiveHint=false, so this description carries meaningful extra context about side effects and scoping.

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

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

Front-loads the core action and effect, then packs prerequisites, duplicate warning, and removal path into two tight sentences. 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?

For a 3-param mutation tool with no output schema, the description covers purpose, required input source, side effects, duplicate risk, and cleanup alternative. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all 3 parameters including smartsiteId default and carouselTitle maxLength. The description clarifies where templateId comes from, which is slightly useful, but doesn't add syntax or format details beyond the schema. Baseline 3 is 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?

States a specific verb and resource ('Show an existing product on the linked account's SmartSite as a tile visitors can buy from'), distinguishing it from siblings by describing the visible effect. An agent can tell this apart from swop_add_link or swop_create_product without opening their schemas.

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

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

Explicitly names where to get the required id (swop_create_product, swop_list_my_products), warns to check swop_get_my_smartsite to avoid duplicates, and points to swop_remove_link for removal. Covers when, prerequisites, and alternatives.

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 genuine behavioral context beyond that: status semantics (paid = money arrived, settled = seller paid out) and the visibility restriction ("Only the linked account's own checkouts are visible"). It stops short of describing error/empty behavior 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?

Three sentences, front-loaded with the purpose, then the polling guidance, then the visibility constraint. Every sentence adds distinct value with no filler or repetition of the name/title.

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 explains the shape of the return (status enum, payment request, line items) and what the key statuses mean. Combined with the annotation safety profile, an agent has everything needed to call and interpret 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 description coverage is 100% for the single intentId parameter, so the schema carries the format and pattern details. The description only implies the link to swop_create_checkout's return value without restating syntax, which meets the baseline 3 when structured fields do the heavy lifting.

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

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

The description opens with a specific verb+resource ("Read back a checkout") and explicitly ties it to its sibling creator (swop_create_checkout). It enumerates the returned fields (status, payment request, line items), so an agent knows exactly what this tool yields versus other get_* 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 clear timing guidance: poll after the buyer has been shown the payment, and it names the lifecycle states that matter (paid vs settled). The alternative direction (use swop_create_checkout to create) is implied rather than stated as a contrast, so it falls just short of the top score.

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, non-destructive, closed-world), and the description adds genuinely new behavior: it returns the closest curated answer or explicitly reports that the topic is not covered, which sets expectations about partial/failed matches. It still doesn't say whether answers are static/versioned or subject to rate limits, 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?

Three tight sentences: what it does, when to use it vs the alternative, and what it returns. No filler, and the purpose is 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?

For a single-parameter, read-only lookup with no output schema, the description covers purpose, routing, coverage topics, and return semantics. The only minor gap is that it doesn't characterize the shape of a returned answer (e.g., is it free text or structured), which the absent output schema leaves unspecified.

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

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

Schema description coverage is 100% and the single query parameter is already documented with examples and a 240-character limit. The description adds only the 'plain words' framing, which largely duplicates the schema; baseline 3 is 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?

Specific verb ('look up') plus resource (Swop's own curated how-to answers) with the covered topic areas named. It explicitly distinguishes itself from the swop_get_my_* data tools, so an agent can separate documentation lookup from data retrieval 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 an explicit trigger ('when the user asks how a Swop feature works') and an explicit alternative path ('for their own data use the swop_get_my_* tools instead'). The when/when-not boundary is stated rather than inferred.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds useful content about what is returned (total USD and per-asset breakdown) but says nothing about refresh timing, caching, or account-link prerequisites that would go beyond the annotations.

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

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

Two tight sentences with no waste: the return payload is front-loaded and the sibling redirect follows. Every clause carries information the agent needs.

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 adequately sketches the return shape (total USD plus per-asset breakdown) and the sibling relationship. It is complete for a simple parameterless read; only the absence of any note on account-link state or freshness keeps it from being fully exhaustive.

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. Baseline 4 applies for a parameterless 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 names a specific resource (the linked Swop account's wallet balances) and characterizes the payload as a snapshot with total USD plus a per-asset breakdown, which is concrete. It also explicitly distinguishes itself from swop_list_my_tokens, so an agent can separate the two 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?

It gives an explicit alternative and the condition that selects it: for launched tokens or merchant Bucks, use swop_list_my_tokens instead. There is no broader when-to-use or prerequisite guidance, but the key routing decision (balances vs. token listing) is covered.

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 provide readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds useful behavioral context by noting it covers both sales and purchases and reports payment, escrow/settlement, and fulfillment status, but it does not address return shape, pagination, or ordering 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?

The description is one tight sentence that front-loads the main purpose and packs in scope plus displayed statuses without any filler. Every clause contributes useful information, making it highly efficient.

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

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

Given zero parameters, read-only annotations, and a simple retrieval purpose, the description is largely complete: it identifies the account scope and the types of orders and statuses shown. It could be slightly more explicit about return format or recency bounds, but this is minor for such a 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?

The input schema has zero parameters and 100% schema coverage, so the description carries little parameter burden. The mention of "recent" and "linked Swop account" adds some contextual meaning, but with no parameters to document, the baseline of 4 is 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 clearly states the tool retrieves recent marketplace orders for the linked Swop account, covering both sales and purchases. It specifies the resource (orders) and useful scope (both directions), which is more specific than mere repetition of the title, though it does not explicitly contrast with 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?

Usage context is implied: this is for viewing account-specific orders, as opposed to market-wide tools like swop_get_orderbook or account tools like swop_get_my_balances. However, there is no explicit statement about when to use this tool versus alternatives, so an agent must infer the applicable scenario.

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, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: the call fails with a connect-account prompt when no Swop account is linked, which is a non-obvious failure mode.

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, each doing work: what it returns, which sibling to use instead, and the failure mode. Front-loaded with the resource and its contents.

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 compensates by naming the returned fields (name, email, SmartSites/handle/bio) and the failure condition. For a zero-parameter read tool, 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?

Zero parameters, so there is nothing to document; the baseline for an empty schema is 4. The description correctly implies no arguments are needed by framing it as fetching 'the linked user's own' account.

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 ('Get my profile') and enumerates the returned content: name, email, and SmartSites with handle/bio. It explicitly distinguishes itself from swop_lookup_identity and swop_search_identities, which are the sibling tools that fetch other people's profiles.

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 rule: use swop_lookup_identity or swop_search_identities for anyone else's profile. That is the exact boundary an agent needs to route between this tool and its closest 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 mark readOnlyHint=true and destructiveHint=false; the description adds useful context by stating it returns a current snapshot and that returned item ids can be used for removal, plus the workflow warning that calling it first keeps edits additive. It does not provide deep behavioral details like pagination/rate limits, but for a simple read tool the combination is strong.

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 action, uses a compact list to convey return contents, and closes with the one usage rule that matters. Every sentence carries operational value; there is 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?

For a simple read-only getter with no output schema and one optional parameter, the description is nearly complete: it names the main returned fields, flags removal ids, and explains the prefetch purpose. A small gap is that it doesn't describe the output shape or whether the result includes any account-level/workspace distinctions, but this is minor at this complexity.

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

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

The schema fully documents the only optional parameter ('Specific SmartSite id (default: primary)'), so the baseline is 3. The description does not add much about the parameter itself beyond implying the linked account's default/primary SmartSite is retrieved, so no extra semantic lift is provided.

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

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

The description names a specific verb ('Get'), a concrete resource ('the linked account's current SmartSite'), and enumerates what is returned (bio, appearance, links with item ids, product tiles, viewUrl). It clearly positions the tool as the read-before-edit counterpart to swop_update_my_smartsite and the add/remove link tools, so an agent can distinguish it from siblings without opening schemas.

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

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

The description explicitly states when to invoke it: 'ALWAYS call this before adding or changing things so edits stay additive.' It gives a strong trigger for use, but it does not name alternative tools or state conditions when this tool should not be used, falling just short of full explicit 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, openWorldHint=true, and destructiveHint=false, so safety is covered. The description adds genuinely non-obvious behavior beyond that: the same link returns a checkout-style product page to a person but an x402 USDC payment challenge to an agent. It does not cover link lifetime or auth requirements, 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?

Two sentences, zero preamble, with the core behavior front-loaded before the usage cue. The trailing enumeration 'chat, a social post, or a message' is mildly padded but still earns its place by naming concrete share surfaces.

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

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

With only two fully documented parameters and no output schema, the description carries the right burden: it explains what the returned link does in both consumption modes. It leaves minor questions unanswered (link permanence, whether re-requesting returns an identical link), but nothing an agent needs to invoke 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 description coverage is 100%, with both handle ('Seller swop.id, e.g. "travis.swop.id"') and sku ('Product sku/id from swop_get_store') documented, including the cross-reference to the sibling that produces the sku. The description adds no parameter-level meaning, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Get one link') and explains the dual behavior of the resulting artifact — a human-facing product page with a Buy button versus an x402 USDC payment challenge for agents. This is more specific than most siblings, though it never explicitly distinguishes itself from swop_add_link, swop_remove_link, or swop_pay_x402_link.

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 concrete usage context: 'Use this to share a product in chat, a social post, or a message.' It gives a clear when-to-use but names no alternatives or exclusions, so the agent must infer this is the retrieval/share path rather than the creation path (swop_add_link) or the pay path (swop_pay_x402_link).

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

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

Annotations only cover the read-only/open-world safety profile, but the description adds the real behavioral payload: the x402 flow, the first request returning HTTP 402 with payment instructions (amount, network, pay-to address), and the retry with a signed X-PAYMENT header returning a receipt. This is context no structured field provides.

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?

Purpose is front-loaded and every sentence carries information, but the payment-workflow instructions expand the description well beyond a one-line read tool. They earn their place, though the paragraph is longer than needed for pure tool selection.

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 covers what comes back (products, USDC prices, buyUrl) and how to act on it via the x402 handshake. An agent has everything needed to call this and interpret the result correctly.

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

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

Schema coverage is 100% and the single handle parameter is already documented with an example format in the schema. The description adds only that the handle identifies the seller whose storefront is read, so the schema does the heavy lifting and a baseline 3 is 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?

States a specific verb and resource: lists the products a given swop.id sells on their SmartSite, including USDC prices and each product's x402 buyUrl. It explicitly distinguishes itself from the sibling swop_list_my_products, which covers the caller's own catalogue.

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?

Names the alternative (swop_list_my_products) and the condition selecting it, then gives the end-to-end purchase procedure for the returned buyUrl. It also sets an explicit when-not/precondition: get user confirmation on product, price, and seller before paying.

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 agent knows this is a safe, non-mutating, closed-world read. The description adds only the 'currently' framing of live state; it says nothing about return format, ordering, or whether the list is scoped per linked account beyond the opening phrase.

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 with the resource and scope front-loaded, followed by the trigger condition. 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?

With no output schema and no parameters, the description carries the return-value burden lightly but adequately: it tells the agent the result is the set of currently allowed framing websites. Complete enough for a simple read-only list.

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 per the rubric the baseline is 4. The description correctly implies the scope is the linked account rather than requiring any input.

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 ('Show') and resource ('which websites may currently display the linked account's Swop checkout in a frame'), which is clear and distinct from siblings like swop_get_checkout. It does not explicitly name the add/remove siblings it relates to, so it falls short of full sibling differentiation.

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

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

'Use before adding or removing one so the user can see what is already allowed' gives clear situational guidance and implicitly points at the register/remove siblings. It omits any when-not condition, 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that only the linked account's own products are returned and enumerates the response fields, which is valuable given no output schema, but it says nothing about pagination, ordering, or result 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?

One tightly written sentence with a front-loaded scope statement, the returned fields in a parenthetical, and follow-up tool routing. Every clause earns its place.

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 list tool with no output schema, the description supplies exactly the missing pieces: the result fields, the ownership scope, and the downstream tools that consume the returned id.

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 there is nothing for the description to disambiguate; baseline 4 applies. No parameter documentation is required here.

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 ('List the linked account's OWN products') plus the returned fields (id, name, price, inventory, status). It explicitly distinguishes itself from the sibling swop_get_store, which browses another seller's products.

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

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

Explicitly routes the agent: use swop_get_store to browse another seller's products, and use the returned id with swop_update_product (edit/unlist) or swop_feature_product. Both the when-to-use and the alternative are named.

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 (readOnlyHint=true, destructiveHint=false, openWorldHint=false). The description adds genuinely useful behavioral context beyond them: merchant Bucks are STORE CREDIT with 2 decimals and must never be summed into a portfolio/cash total, and an empty list is normal rather than an error.

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 tight sentences, each earning its place: scope first, sibling routing second, and the store-credit/empty-list caveats last. 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?

With no output schema, the description carries the return-value burden, and it discloses the empty-list semantics and the isStoreCredit flag. It does not describe the shape of a returned token entry, which is a minor residual gap rather than a blocking one.

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 per the rubric the baseline is 4. Schema coverage is 100% and there are no inputs for the description 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?

Names a specific resource (community tokens and merchant Bucks launched on Base) and its scope (the linked account), and explicitly distinguishes itself from swop_get_my_balances. An agent can tell exactly what this returns 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?

States the condition that selects the sibling: use swop_get_my_balances for the overall wallet total. Also clarifies that an empty list is a valid result, not a failure. No explicit when-not-to-use beyond that, but the routing guidance is 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds valuable behavioral context by explaining the two events and their real-world timing (payout may be days after a card sale). It still doesn't mention pagination or result shape, but the added semantic detail is substantive.

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 front-loaded sentences that each carry information: purpose, event semantics, and usage timing. The parenthetical on payout timing is slightly long but does earn its place by disambiguating event meaning.

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

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

With no output schema, the description carries the burden of describing what is returned, and it does so — endpoints plus the two available events. Adequate for a zero-parameter read tool, though it omits any note on result size or formatting.

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

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

There are zero parameters, so per the rubric the baseline is 4. The description adds nothing parameter-related because there is nothing to document, which is 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?

States a specific verb (Show/list) and resource (webhook endpoints Swop notifies when the linked account gets paid) plus the events available. Clearly separable from sibling mutations like swop_register_webhook and swop_remove_webhook without opening any schema.

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

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

Explicitly tells the agent when to call it: 'Use before adding or removing one,' which routes it relative to the register/remove siblings. It does not name those sibling tools or state when not to use it, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds meaningful behavioral context: case-insensitive exact matching and the set of returned fields. This goes beyond the annotations without contradicting them.

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 compact sentences with no filler. The core behavior and output are front-loaded, and the alternative tool is mentioned without extra detail.

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

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

For a single-parameter, read-only lookup tool with a fully documented schema and clear sibling distinction, the description covers the essential behavior and return fields. No critical missing context for an agent to invoke 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 description coverage is 100%, and the handle parameter is fully documented in the schema. The description reinforces the parameter with an example but does not add significant new semantic information beyond 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 clearly states the action ('Resolve'), the resource (an exact swop.id handle), and the result (profile details with display name, avatar, and wallet addresses). It also distinguishes itself from swop_search_identities by emphasizing exact match versus fuzzy search.

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 explicitly provides usage guidance: it is for exact matches and directs the agent to use swop_search_identities for fuzzy search. This gives clear when-to-use/alternative 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 mark it as a non-read, non-destructive write; the description adds real behavioral context beyond that — that this is a security allowlist setting and that a leaked API key cannot bypass it. It does not state what happens on duplicates, required permissions, or the response shape, leaving a modest 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?

Front-loaded with the action and scope, then rationale, then format rules, then the user-confirmation step. Four sentences with little waste, though the security-rationale sentence is more context than strictly necessary.

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 2-param registration mutation with no output schema and annotations already covering the safety profile, the description covers purpose, format, and prerequisites. Missing only edge-case behavior (duplicate origin handling) and any auth notes.

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 goes further by specifying the exact origin format (scheme+host only, https or localhost http, no wildcards, no path), which the schema's terse 'e.g. https://acme.com' does not fully convey. The label parameter is left to the schema.

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

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

States a specific verb (register/allow) and resource (one website framing the account's checkout), which an agent can distinguish from the sibling list/remove embed-origin tools by inference. It does not explicitly name those alternatives, so it falls just short of full sibling differentiation.

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 concrete operating context ('only registered origins can ever frame the checkout') and an explicit behavioral instruction ('Confirm the exact origin with the user first'). It stops short of naming the alternatives (swop_list_embed_origins, swop_remove_embed_origin) that would make routing unambiguous.

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

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

Annotations only cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description goes well beyond, disclosing the one-time signing secret that cannot be retrieved again, the Swop-Signature header format and HMAC construction, and a ~15 hour retry window for failed deliveries — exactly the behavioral context an agent needs.

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 outcome ('Get notified the moment the user gets paid'), then layers in the one-time secret warning, signature format, and retry window. Every sentence carries operational value, including the user-confirmation instruction.

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?

No output schema exists, so the description correctly covers the return value (a signing secret shown ONCE) and delivery semantics (signature header, retries). Combined with annotations and full schema descriptions, an agent has everything needed to call and use 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, and the description adds real meaning by explaining the event payloads and when they fire, which enriches the 'events' parameter beyond its bare enum. It does not restate the https/localhost rule or maxLength, which the schema already covers.

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 (register) and resource (an https webhook URL) plus the triggering events (checkout.paid, payout.released). An agent can distinguish it from swop_list_webhooks, swop_remove_webhook, and swop_test_webhook purely from the description.

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 clear context ('the moment the user gets paid') and a prerequisite workflow step ('Confirm the exact URL with the user first'). It does not explicitly name alternatives like swop_test_webhook or swop_remove_webhook, so an agent must infer lifecycle routing rather than being told.

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 flag destructiveHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds the concrete consequence — the site can no longer display the checkout — which is meaningful context beyond the annotation. It does not mention reversibility or permission requirements.

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, each earning its place: action, argument source, and effect. The outcome is front-loaded with no filler or redundancy.

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 destructive mutation with no output schema, the definition covers action, argument provenance, and post-condition, and annotations carry the safety signal. Minor gap only in not stating permissions or whether the removal is reversible.

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 single id parameter is already documented as coming from swop_list_embed_origins, so the schema does the heavy lifting. The description repeats that provenance without adding format or validation detail, which is the expected baseline.

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

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

States a specific verb+resource (remove a website from the checkout embed-allowlist) and ties it to the linked account's checkout, which distinguishes it from sibling mutations like swop_register_embed_origin or swop_remove_link. An agent can identify the effect without inspecting 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?

Explicitly directs the agent to swop_list_embed_origins as the source of the required id, giving clear provenance for the argument and implying a list-then-remove workflow. It does not state when not to use it or contrast against swop_register_embed_origin, so it stops short of full when/when-not 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 already mark this as destructive (destructiveHint=true), and the description reinforces this by saying 'Remove' and 'Confirm with the user first.' It adds useful behavioral context about sourcing the parameters from swop_get_my_smartsite, which is beyond what the annotations convey.

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

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

Two focused sentences deliver the core action, the item categories, the parameter sourcing workflow, and the user-confirmation requirement. There is no filler or repetition of already-available schema information.

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

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

For a destructive removal tool with strong annotations and full schema coverage, the description provides everything an agent needs: what to remove, how to identify the target, the exact source of identifiers, and the required user confirmation. No output schema is needed for a removal action.

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

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

Although schema coverage is 100%, the description adds meaning by explaining the relationship between itemId and contentType and how to obtain them from swop_get_my_smartsite. The mapping from contentType enum values to real-world item categories provides semantic value beyond raw enum names.

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

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

The description uses a precise verb ('Remove') and clearly defines the resource: links/icons/info-bars/product tiles from the SmartSite. It distinguishes itself from siblings like swop_add_link by focusing on the removal use case and enumerating the exact item 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 description gives explicit how-to guidance: obtain the item's id and contentType from swop_get_my_smartsite, including a mapping from human-friendly categories to contentType enum values. It also instructs the agent to confirm with the user first, which is critical for a destructive operation.

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?

Going beyond the destructiveHint/readOnlyHint annotations, the description discloses the concrete side effect that 'Pending deliveries to it are dropped' and that user confirmation is expected. It still doesn't state whether removal is reversible or what the response looks like, but it adds real behavioral value over the annotations.

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

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

Three short sentences, front-loaded with the core action and ending with the safety instruction. No filler, nothing 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 single-parameter destructive tool with no output schema, the description covers action, side effect, and caution. Only marginal gaps remain, such as reversibility or how to restore a webhook.

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 single 'id' parameter is fully documented in the schema (100% coverage) including its source ('Webhook id from swop_list_webhooks'). The description adds no parameter detail beyond that, so the baseline of 3 applies.

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

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

States a specific verb+resource ('Stop sending events to one of the linked account's webhook URLs'), which is unambiguous and lets an agent distinguish it from swop_list_webhooks, swop_register_webhook, and swop_test_webhook without opening schemas.

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

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

The line 'Confirm with the user first' gives concrete usage guidance for a destructive operation. It doesn't explicitly name alternatives (e.g., re-adding via swop_register_webhook), but the context of use is 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds useful behavioral context—searching by handle/display name and returning public EVM/Solana addresses—but does not detail match semantics, ordering, or result limits beyond what the schema already provides.

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 concise sentences: the first defines the action and scope, the second lists return values and the intended use case. There is no filler, repetition of schema constraints, or unnecessary detail.

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 low-complexity, 2-parameter read-only search tool, the description covers the return values and the core use case. The only noticeable gap is not clarifying the relationship or difference from swop_lookup_identity, but that does not prevent a safe and correct 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 100: 'query' and 'limit' both have explicit descriptions explaining meaning and constraints. The tool description only reiterates 'handle or display name' and adds no additional format or behavior details, so the baseline 3 is 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 verb ('Search') and resource ('Swop user identities (swop.ids)') and lists concrete return fields. It does not explicitly distinguish itself from the sibling tool swop_lookup_identity, so it stops short of a 5.

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

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

It provides clear usage context: 'Use this to find a user or resolve a name to a wallet address.' However, it does not mention when to prefer alternatives like swop_lookup_identity, so it lacks explicit exclusions or when-not-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 already declare non-read-only, non-destructive, open-world behavior, and the description adds real value on top: the payload is a signed 'ping', the call fires immediately ('right now'), and it hits an external endpoint and returns an HTTP status. It doesn't cover failure/timeout semantics, but the safety and side-effect profile is well conveyed.

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, zero filler, with the action and its return value front-loaded and the usage note trailing. Every clause earns its place.

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 action tool with no output schema, the description covers what it does, the payload semantics, and the returned value (HTTP status), and annotations cover the safety profile. Nothing material is missing.

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

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

Single parameter with 100% schema description coverage; the schema already documents that 'id' comes from swop_list_webhooks. The description adds nothing parameter-specific, which is acceptable given full schema coverage.

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 ('POST a signed ping event to ... webhooks ... report the HTTP status'), naming the exact action and its observable result. It is clearly distinguishable from sibling webhook tools like swop_register_webhook, swop_list_webhooks, and swop_remove_webhook.

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

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

'Use to confirm an integration before relying on it' gives a clear selection context for when to reach for this tool. It offers no explicit exclusions or named alternatives, but the purpose is narrow enough that alternatives aren't ambiguous.

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 it's a write operation (readOnlyHint false) but not destructive (destructiveHint false). The description adds the partial-update behavior ('pass only what you want to change') and that backgroundGradient 'clears the solid color' (though that is also in the schema). It provides useful context beyond generic annotations without contradiction.

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 well-structured sentences, front-loaded with the core purpose and followed by routing guidance. No wasted words; every sentence earns its place.

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

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

Given 10 optional parameters with full schema descriptions and no output schema, the description covers the overall scope and usage clearly. It could mention return behavior or error scenarios, but for a partial-update tool with clear schemas, it is sufficiently 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?

Schema has 100% parameter descriptions, so baseline is 3. The description lists the parameter categories but does not add new semantics beyond the schema's existing per-field descriptions. It repeats what the schema already says, so it adds no extra value here.

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 tool edits the linked account's SmartSite and explicitly lists the fields (name, bio, background, theme, font, header layout). It distinguishes from siblings by naming alternatives for adding links and products, so an agent knows exactly what this tool does and does not do.

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 explicitly states when NOT to use this tool: for links/buttons/info bars use swop_add_link, for products use swop_create_product / swop_feature_product. It also instructs to 'pass only what you want to change', giving clear usage intent. This is excellent routing guidance.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description aligns with those flags. It adds useful behavioral nuance: edits are partial, unlisting is done via status='archived', and user confirmation is required for name/price changes. It does not detail side effects beyond those, but the annotation lowers that burden.

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 three tight sentences with no filler. It front-loads the core edit/unlist purpose, then gives the essential operational rules, and every sentence contributes a distinct fact an agent needs.

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 mutation tool, the description covers the key orchestration rules: partial updates, provenance of productId, unlisting behavior, and confirmation requirements. The schema fully describes each parameter. The only notable gap is the absence of return/error behavior, which matters more because there is no output schema.

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 handles individual parameter meanings. The description adds value with patch semantics ('ONLY the fields to change'), clarifies unlisting through status, and flags name/price changes as requiring user confirmation, which is not apparent from the schema alone.

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 action ('Edit') and the resource ('one of the linked account's products'), and additionally covers the unlist behavior. This distinguishes it from sibling tools like swop_create_product and swop_list_my_products without relying on the title alone.

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

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

It gives concrete usage instructions: pass productId, send only the fields to change, leave omitted fields unchanged, and set status to 'archived' to unlist. It also instructs the agent to confirm price and name changes with the user first. It does not explicitly contrast with create/feature alternatives, so it stops short of a 5.

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