Use when selling a big item: fitness gear, hot tubs, furniture, appliances. Pickup handled.
Scored across 23 tools
Most tools map to distinct resource+action pairs (catalog browse vs. listing draft vs. seller management vs. pricing vs. support). A few boundaries blur: listing_create vs. listing_crosslist_draft, mark_sold_elsewhere vs. seller_remove_listing, and pricing_quote_crosslist vs. pricing_quote_payout all do similar-sounding things, though descriptions do draw the distinctions for a careful reader.
Nearly every tool follows a namespace_verb_noun pattern (catalog_get_listing, seller_update_listing, pricing_quote_payout, support_create_ticket), grouped by domain prefix. The lone exception is mark_sold_elsewhere, which drops the prefix and pattern, a minor deviation.
23 tools is on the heavy side for the apparent scope, and the set carries redundancy (two ways to create a listing, two ways to take a listing down, three pricing tools). The domain is genuinely broad (browse, sell, price, deliver, support), so most tools are justified, but it sits in the borderline 16-25 band.
Seller lifecycle is well covered: create, edit, remove, relist, list listings/offers/sales, respond to offers, plus pricing, delivery quoting and support escalation. Gaps are acknowledged rather than hidden (no description editing, no payout-sent tracking, no buyer purchase/order flow, no direct buyer communication), leaving agents with a few dead ends that route to support.
The Commonplace account this connection acts for: name, and a masked phone and email. Use it to confirm the right account before creating or changing anything. phone: null only means the account has no phone on file; each listing made with listing_create carries its own pickup phone (seller_phone), which is how Commonplace reaches the seller about that listing.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds genuine value beyond that: it discloses data masking (masked phone/email), that phone:null is a legitimate state rather than an error, and the cross-tool relationship with listing_create's seller_phone.
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 what the tool returns, then the usage cue, then the seller_phone clarification. Three sentences, and the final one runs long but it disambiguates a field that could otherwise confuse an agent, so it 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 no-parameter, read-only identity tool the description covers enough: what comes back, the masked/absent-value semantics, and when to call it. An output schema would make the return-shape note unnecessary, but the masking behaviour is still useful context to state.
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 the baseline is 4. The description uses the space well by clarifying the semantics of what looks like a parameter/output field (phone: null) rather than padding with irrelevant parameter talk.
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 precisely states what is returned: the acting account's name plus masked phone and email, which clearly distinguishes it from the listing/catalog/pricing siblings. It is a noun-phrase content statement rather than a crisp verb+resource, but an agent can immediately tell what this tool is for.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use guidance: 'Use it to confirm the right account before creating or changing anything.' No alternative sibling competes for the identity-confirmation role, so no exclusions are needed, though the guidance could be a touch more concrete about workflows.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full public detail for one listing: buyer_price_usd (what a buyer pays, delivery within 100 miles included), availability, condition, location, dimensions, weight, highlights, the seller's description, photo links, when it was listed, is_yours (whether it belongs to this account), and hsa_fsa_eligible (whether HSA or FSA funds can pay for it). Condition is in the sell form's spelling (New, Like New, Excellent, Very Good, Good, Fair, Poor, Used) when it is one of those grades, otherwise the seller's own words. Categories offer different grades; the ones a new listing can use are its category's condition_options from listing_resolve_category. original_price_usd is the item's retail price new, when known; a price change does not set it. Fields that are not on file come back null.
| Name | Required | Description | Default |
|---|---|---|---|
| listing_id | Yes | The listing's numeric id, from a search result or seller_list_listings. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, and the description goes beyond them by defining the returned payload's semantics: condition grade spelling, that original_price_usd is retail not a price change, the meaning of is_yours and hsa_fsa_eligible, and that absent fields come back null. It does not cover error behavior for a missing id, 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?
The enumeration is long but front-loaded with the core action and every clause carries information the agent needs in the absence of an output schema. It is dense rather than padded, though the field list could be tightened.
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 takes on the burden of describing the return shape and does so thoroughly, including null semantics and special-field behavior. Only edge cases (not-found/error handling) are left unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With a single parameter at 100% schema description coverage, the schema fully documents listing_id and its provenance. The description adds nothing about the parameter, 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 ('Full public detail for one listing'), which is clearly distinct from the sibling catalog_search_listings that returns collections. It doesn't name a sibling explicitly, but the singular scoping makes the retrieval role 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?
Usage is only implied: the schema's listing_id text points to 'a search result or seller_list_listings,' sketching a browse-then-fetch workflow. There is no explicit when-to-use versus catalog_search_listings or when a full-detail fetch is warranted over a search result.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every category new listings are filed under, with its slug; departments, slugs that cover every category in them (furniture, fitness); and older_categories, slugs that older live listings still carry, which search accepts too. Use a slug with listing_resolve_category, the pricing tools or search to avoid guessing. A category's listings can be stored under an older slug (Peloton Bike's under peloton-bike-2nd-gen), which searching the category covers. A department does not cover older_categories: to include them, add their slugs to the search's category list (sofas,living-room-sets).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this a non-destructive, non-open-world read, so the bar is low, yet the description adds real domain behavior: listings may be stored under an older slug (Peloton Bike under peloton-bike-2nd-gen), a department does not cover older_categories, and including them requires adding their slugs to the search's category list. That is non-obvious semantics an agent would otherwise get wrong.
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 return shape is front-loaded and every sentence carries distinct information (structure, usage, older_slug behavior, department caveat). The third and fourth sentences are dense and slightly run-on, but no sentence is 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 full burden of describing the return payload and does so: it names the three groupings and their contents. For a zero-parameter read tool it leaves nothing an agent needs to call it or interpret the result.
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 no parameters and the schema is empty at 100% coverage, so parameter semantics rest on the explicit baseline of 4. The description correctly adds no parameter detail because there is none to add.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states exactly what the tool returns: every category new listings are filed under, plus the departments and older_categories groupings with their slugs. It names the sibling tools that consume those slugs (listing_resolve_category, pricing tools, search), so an agent can position this tool relative to alternatives 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?
It clearly directs the agent to use a returned slug with listing_resolve_category, the pricing tools, or search 'to avoid guessing', establishing the tool as the slug-discovery step. It gives no explicit when-not-to-use condition, but the workflow context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search live Commonplace inventory by words, category, place (deliver_to alone returns some listings near it, not every one), or any mix. Results are active and buyable. outcome: ok; none; none_within_limits (every match is in hidden); out_of_budget (matches only outside the price range; examples ignore deliver_to); undeliverable (none reaches deliver_to; examples say how far). With deliver_to, each result carries delivery (known, deliverable, driving distance_miles, fee_usd, total_usd). Candidates come from the words or categories plus the catalogue's proximity ranking, not the whole catalogue: to be thorough, also search category_hint and its department. Up to 40 are checked per call, roughly nearest first; with max_distance_miles, one already well past it in a straight line is not checked but counted in too_far (distance_is_straight_line: a lower bound, not a drive). delivery_checked, candidates_considered and candidates_unchecked (could be inside the limits, never checked) say how far it got; next_offset, passed back as offset, checks the rest. cheapest and most_expensive spend all 40 checks and return the best (results_not_shown counts the rest; a limit up to 40 returns them); any sort orders only what was checked. farthest_checked_miles, the longest drive measured, can pass the radius. hidden counts every candidate left out, once each, by reason, with its nearest or cheapest examples. When no title matches, the category the words point to is browsed (no_title_matched) or the outcome is none; matched_on names looser words that matched. more_available: candidates_unchecked (see next_offset), or more_matches_unread: more listings match than one search reads, which offset cannot reach; narrow the words, category or price.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | best_match is relevance order and says nothing about price. With deliver_to, cheapest orders by the delivered total and nearest by driving distance (nearest needs deliver_to). | |
| limit | No | How many listings to return (default 5, at most 40). | |
| query | No | What to look for, e.g. "peloton bike+" or "sectional sofa". Words match titles loosely, with only a few everyday synonyms (couch and sofa, fridge and refrigerator) ("hot tub" misses a listing titled Jacuzzi: search its category), though "+" and "plus" count as the same. Optional when category is given: without words, the search browses the category. | |
| offset | No | With deliver_to: a previous call's next_offset, with the same other arguments, to check the candidates it did not reach (hidden then counts only that call's checks). Use it rather than price bands to be thorough: min_price_usd compares the price before delivery, so bands can miss a listing. | |
| category | No | Only these categories: a slug from catalog_list_categories, listing_resolve_category or a result's category_slug, or several separated by commas (sofas,sectionals,general-furniture). A department (furniture) or parent (peloton) covers every category beneath it, and a category covers the older slugs its listings are stored under (peloton-bike returns peloton-bike-2nd-gen listings). With words too, only this category is searched, and words matching nothing in it return none. | |
| deliver_to | No | Where it would be delivered: a 5-digit ZIP or "City, ST". Keeps only items that can be delivered there, which can be far away. To find items near a place, give the place here with max_distance_miles. | |
| max_price_usd | No | Highest price, inclusive, in US dollars: buyer_price_usd, or with deliver_to the total with delivery. A listing whose buyer price alone is over it is not a candidate at all. For "under $1,200", pass 1199.99. | |
| min_price_usd | No | Lowest buyer_price_usd, inclusive, in US dollars. Always compared with buyer_price_usd, with or without deliver_to. | |
| hidden_examples | No | How many listings each hidden reason shows (default 10 for too_far, 20 for the others); counts are always complete. | |
| max_distance_miles | No | With deliver_to: only items within this many driving miles of it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With only safety annotations present, the description carries the full behavioral burden and does so richly: it documents outcome values (ok, none, out_of_budget, undeliverable, etc.), candidate sampling (up to 40 checked, proximity ranking), hidden reasons, pagination via next_offset, and what more_available and more_matches_unread mean. This is far beyond the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense block of semicolon-separated clauses covering outcomes, candidates, hidden counts, pagination, and sort semantics. Much of this detail duplicates schema or could be structured more clearly, making it hard to parse despite the front-loaded purpose.
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 absence of an output schema, the description fully explains return-relevant behavior: outcome statuses, delivery fields, hidden reasons, pagination tokens, and candidate limits. An agent has enough context to call this complex search 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%, so each of the 10 parameters already has its own documented meaning. The description adds some behavioral nuance around deliver_to, max_distance_miles, offset, and sort, but much of the parameter detail remains redundant with the schema, warranting the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: "Search live Commonplace inventory by words, category, place... or any mix." It also states the result nature ("Results are active and buyable"), which is enough to distinguish it from retrieval-by-id siblings like catalog_get_listing and catalog_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 tool's core usage is implied by "Search live Commonplace inventory", and the description gives parameter-level guidance such as using deliver_to with max_distance_miles or using offset to be thorough. However, it never explicitly states when to use this tool versus alternatives like catalog_get_listing or catalog_list_categories, so the guidance remains implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Whether a listing can be delivered to a destination, what delivery adds on top of its buyer_price_usd (0 means it is included), the distance, and the total the buyer pays. When no quote is possible, unresolved says which end could not be placed: "origin" means the listing's own location is unknown, so no address the buyer gives will help. reason is the platform's own wording, and "calculated manually" in it means no quote yet: whenever there is no automatic quote, whichever end is at fault, the team prices that delivery by hand, and needs_manual_quote is true (ask Commonplace support for one: support_create_ticket where this connection has it, otherwise the support line, (516) 357-5989). A quote gives included_miles (free) and per_mile_usd, the category's rate for miles 101 to 200 and beyond 200. Delivery within 100 miles of the item is already included in its price; beyond that a per-mile fee applies, and most items cannot travel beyond 1,500 miles.
| Name | Required | Description | Default |
|---|---|---|---|
| listing_id | Yes | The listing's numeric id, from a search result. | |
| destination | Yes | A 5-digit ZIP or "City, ST". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish a safe read-only, non-destructive, closed-world operation, yet the description adds substantial behavior: the meaning of `unresolved` values, that `reason` is the platform's own wording, that "calculated manually" implies no quote exists, the manual-quote path, and the included_miles/per_mile_usd tiering with the 1,500-mile limit. This is well beyond what annotations cover.
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 deliverability question before edge cases. It is long and dense, but most sentences carry non-obvious pricing rules that the agent needs; a few clauses could be tightened, keeping it just under the top mark.
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 full burden of explaining return values (unresolved, reason, needs_manual_quote, included_miles, per_mile_usd) and it does so thoroughly for a complex domain. An agent has enough to interpret results and act on the manual-quote case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters are fully documented in the schema, so baseline is 3. The description adds only indirect value, clarifying that a bad `origin` means no destination value the buyer supplies will help, but adds no syntax or constraints beyond the schema's ZIP / "City, ST" spec.
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 up front: whether a listing can be delivered to a destination, what delivery adds to buyer_price_usd, the distance, and the total. An agent can distinguish it from pricing siblings (pricing_quote_payout, pricing_quote_crosslist) 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?
Gives conditional routing for the no-quote case (needs_manual_quote is true, so contact support via support_create_ticket or the support line), which is genuine when-to-use guidance. It does not explicitly contrast with pricing_get_guide or state when delivery quoting is preferred over other pricing calls, so it falls short of full 5-level guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add photos to a draft that listing_create saved without photos, and publish it. Only drafts this connection's account created through the connector can be finished here. Requires confirmed: true.
| Name | Required | Description | Default |
|---|---|---|---|
| draft_id | Yes | A draft_id from listing_create or from drafts_awaiting_photos in seller_list_listings. | |
| confirmed | Yes | false: nothing is published, and the result says what would be. true: publish, once the seller has agreed. | |
| photo_urls | No | Up to 8 photos. Prefer https image URLs (JPEG, PNG, WebP or GIF, up to 5MB each). A data:image URL works only for a small image: the whole request is limited to 256KB and a larger one is refused before the tool runs. A photo the seller attached in the chat goes in photo_files, never written out here; if the chat app cannot attach it, publish without photos to save a draft and give the seller finish_url. A preview does not download photos: include https links in it anyway so they are checked (a Commonplace link such as /api/img/<listing id>/0 belongs to that listing, and another seller's is a problem there), but send an inline image only with the confirmed call, since writing one out twice costs the seller minutes. EXIF location data is removed. | |
| photo_files | No | Photos the seller attached in the chat. The chat app fills these in (each a download_url and file_id); never write one by hand. They get the same checks as photo_urls. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this a non-read-only, open-world, idempotent, non-destructive operation, so the safety bar is partly covered. The description adds meaningful behavior beyond them: that this action publishes, that it is scoped to drafts owned by the same connection's account, and that confirmed: true is mandatory, which a caller could otherwise miss.
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 action and then the eligibility constraint, with no filler. The final sentence ('Requires confirmed: true') partially repeats what the required-parameter list already enforces, which is the only 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 publish-style mutation with no output schema, the description covers the action, the ownership precondition, and the confirmation gate, which is sufficient for correct invocation. It does not describe what a successful publish returns or the consequences of publishing on the listing's visibility, though the schema touches on preview results.
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 draft_id, confirmed, photo_urls and photo_files are already fully documented, including the dry-run meaning of confirmed. The description only restates the confirmed: true requirement, adding no syntax or format detail beyond the schema; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource pair ('Add photos to a draft ... and publish it') and explicitly distinguishes it from the sibling that creates the draft ('a draft that listing_create saved without photos'). An agent can tell it is not the creation tool and not a plain update tool 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?
It states the precondition (drafts saved by listing_create without photos) and a hard eligibility rule (only drafts created by this connection's account), which is real routing guidance. It stops short of naming alternatives such as listing_discard_draft for drafts that should not be finished, so it is clear context without explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use when the user is selling a large or valuable item (fitness equipment, hot tubs, saunas, golf carts, furniture, appliances), including when also posting to Facebook Marketplace, Craigslist, or OfferUp. Publish a listing for the seller (terms as in the server instructions). Resolve the category with listing_resolve_category first. Condition is required. The category's other questions are optional and can be added after the listing is up. The price the seller asked for on Facebook Marketplace, Craigslist, or OfferUp becomes their take-home on Commonplace. The buyer price includes pickup and delivery. With a photo it publishes live (status live, or in_review outside our categories); with none, a draft is saved and finish_url is where the seller adds photos (or use listing_add_photos). A connection that cannot publish can save a no-account draft with listing_crosslist_draft instead. Drafts never expire or show to buyers; seller_list_listings lists them and listing_discard_draft removes one. Without confirmed: true nothing is saved: the result is a preview of what would be published (public_title, answers as stored, take_home_usd, buyer_price_usd and the fees added on top), with problems listing anything a confirmed call would refuse and ignored_answers any key the category does not ask. Listing is free. The seller is paid their take-home at pickup (bank transfer, Venmo, Cash App, or PayPal), not after delivery. Promote is an optional add-on and this never turns it on. Within minutes of publishing, a description is generated from details and may retitle the listing; it can state things the seller never said, so check it on the listing page (support corrects it; no tool edits one). environment in the result names the deployment: only production reaches real buyers.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Just the item, e.g. "Peloton Bike+ 2022": the platform adds condition and city, and the preview's public_title is the exact result. | |
| answers | No | Answers to the category's required_questions, keyed by the `key` values from listing_resolve_category. Use its exact option strings; where none fits (a brand that is not listed, say), give the real value as written. Condition is not one of them; give it as `condition`. Every answer is a string: a number as digits ("2021"), and for a question of type chips several choices separated by commas, options and the seller's own words alike (the preview's answers show how each is stored). The preview's ignored_answers lists any key this category does not ask. | |
| details | No | Anything else the seller said about the item: age, wear, what is included. Contact details are removed, and the listing's description is generated from it. | |
| category | Yes | The category from listing_resolve_category. An exact slug or name is used as given; anything else is matched with the title, and the preview shows which category it landed in. | |
| condition | No | An exact option from the category's condition_options, given here and not in answers. Where the options name a usage band (rides, uses), grade by usage and put cosmetic wear in details. | |
| confirmed | Yes | false: nothing is saved, and the result is a preview. true: publish, once the seller has agreed to exactly this; with no photos it saves a draft instead, finished at finish_url. | |
| price_usd | Yes | What the seller wants to take home, in US dollars. The transaction and pickup fees and delivery are added on top for buyers. | |
| photo_urls | No | Up to 8 photos. Prefer https image URLs (JPEG, PNG, WebP or GIF, up to 5MB each). A data:image URL works only for a small image: the whole request is limited to 256KB and a larger one is refused before the tool runs. A photo the seller attached in the chat goes in photo_files, never written out here; if the chat app cannot attach it, publish without photos to save a draft and give the seller finish_url. A preview does not download photos: include https links in it anyway so they are checked (a Commonplace link such as /api/img/<listing id>/0 belongs to that listing, and another seller's is a problem there), but send an inline image only with the confirmed call, since writing one out twice costs the seller minutes. EXIF location data is removed. | |
| pickup_zip | Yes | Where the item is: a 5-digit ZIP or "City, ST". The exact address is confirmed before pickup. | |
| photo_files | No | Photos the seller attached in the chat. The chat app fills these in (each a download_url and file_id); never write one by hand. They get the same checks as photo_urls. | |
| seller_name | No | Only if the account has no name on file. | |
| seller_phone | No | Required when the account has no phone on file (account_get_profile shows phone: null); otherwise only to use a different number. A US number that receives texts: pickup is arranged by text, and a landline is accepted but gets none. 10 digits, with or without +1, spaces or dashes. It is saved with this listing. If the account has no phone, it is also saved as a contact number so the next listing does not ask again. It is not used to sign in. | |
| lowest_take_home_usd | No | Optional: the least the seller would take home. Offers that reach it are accepted automatically; it is never shown to buyers. Above price_usd it is set to price_usd. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are sparse (readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false), and the description carries the behavioral load: publishing vs draft outcomes based on photos, the preview-only behavior without confirmed:true, required seller_name/seller_phone only when the account lacks them, payment timing (paid at pickup), fees added on top for buyers, and post-publish auto-generated descriptions that may retitle the listing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The usage trigger is correctly front-loaded, but the body is a dense single block of roughly 20 sentences that jumps between publishing rules, payment, drafts, previews, description generation, and environment. Most content earns its place given the tool's complexity, yet the flowing prose makes it hard to scan for exclusions.
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 13-parameter publishing tool with no output schema, the description covers outcome modes (live vs draft vs crosslist draft), what a preview returns (public_title, answers, take_home_usd, buyer_price_usd, problems, ignored_answers), and the environment field. An agent has enough to call it correctly and interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3; the schema already documents title, price_usd, condition, answers, photos, phone, etc. in depth. The description reinforces cross-cutting semantics (condition required, price is take-home, photo presence determines live vs draft) but adds little parameter detail the schema does not already contain.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Publish a listing for the seller") and scopes the trigger to a concrete seller situation (large/valuable items such as fitness equipment, hot tubs, furniture). It also distinguishes itself from siblings by naming listing_resolve_category, listing_add_photos, and listing_crosslist_draft for adjacent cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use (selling a large/valuable item, also cross-listing to Facebook Marketplace/Craigslist/OfferUp) plus named alternatives and their conditions: listing_crosslist_draft for connections that cannot publish, listing_add_photos/finish_url when there are no photos, seller_list_listings and listing_discard_draft for drafts. Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use when the user is selling a large or valuable item (fitness equipment, hot tubs, saunas, golf carts, furniture, appliances), including when also posting to Facebook Marketplace, Craigslist, or OfferUp. Save a draft and return a confirm link. Nothing is published until the seller opens the link and taps Publish. No Commonplace account is required. When seller_phone is included, the seller is also texted the link. Use this when also posting to Facebook Marketplace, Craigslist, or OfferUp, and when this connection cannot create listings itself. The price the seller asked for on Facebook Marketplace, Craigslist, or OfferUp becomes their take-home on Commonplace. The buyer price includes pickup and delivery.
| Name | Required | Description | Default |
|---|---|---|---|
| zip | No | 5-digit pickup ZIP. City and state work when there is no ZIP. | |
| city | No | ||
| brand | No | ||
| state | No | ||
| title | Yes | ||
| category | No | ||
| condition | No | ||
| price_usd | Yes | Dollars. By default this is what the seller takes home. Pass price_type facebook_buyer_price when it is the price a buyer pays on the other site. | |
| photo_urls | No | https image URLs, or small data:image URLs. They are downloaded and re-hosted. A photo that cannot be fetched is skipped and the draft is still saved. | |
| price_type | No | take_home (the default) is what the seller takes home. facebook_buyer_price is what a buyer pays on the other site. | |
| source_url | No | The other site's listing URL, kept for the assistant. It is not shown to buyers. | |
| description | No | ||
| seller_name | No | ||
| seller_email | No | ||
| seller_phone | No | A US mobile. When present, the confirm link is texted here as well as returned. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations it discloses the full lifecycle: nothing is published until the seller opens the link and taps Publish, no Commonplace account is required, and the seller is texted the link when seller_phone is present — real side-effect information an agent needs. The only gap is a mild tension with readOnlyHint=true, since the description's own verb is 'Save a draft,' a persisted artifact, which the description never reconciles with the read-only hint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The content is useful but the structure is loose: the 'when also posting to Facebook Marketplace, Craigslist, or OfferUp' clause appears twice, and the price/take-home explanation arrives after a redundant second 'use this when' sentence. It is also not front-loaded on the action — the first clause is a use condition, not what the tool does.
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 tool with no output schema, the description covers the essentials an agent needs: the draft/publish gate, the returned confirm link, the SMS side effect, and the price-type semantics. It does not cover what happens with invalid or missing photos, category resolution (there is a listing_resolve_category sibling), or failure modes, but nothing critical to correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 40% schema description coverage across 15 parameters, the description does compensate for the two hardest ones: price_type (the price the seller asked for on the other site becomes their take-home) and seller_phone (triggers the SMS). But it adds nothing for title, description, category, condition, brand, city/state/zip, source_url, seller_name, or seller_email, so roughly half the parameters remain undocumented in both places.
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 gives a specific verb and artifact: "Save a draft and return a confirm link," which is clearly distinct from listing_create (publishes) and listing_add_photos (attaches media). It also scopes the use case to large/valuable items. However, the action statement is buried behind two 'use when' sentences, and the framing leans on the title rather than leading with what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit triggering conditions with concrete item examples (fitness equipment, hot tubs, saunas, golf carts, furniture, appliances) and the cross-listing scenario (Facebook Marketplace, Craigslist, OfferUp). It also states a constraint: use when this connection cannot create listings itself. It does not, however, name a sibling alternative (e.g. listing_create) for the non-crosslist case, and the Facebook/Craigslist/OfferUp clause is repeated verbatim twice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Discard a draft that listing_create saved without photos: it leaves drafts_awaiting_photos, its finish_url no longer opens it, and listing_add_photos can no longer finish it. Only this account's own connector drafts can be discarded. A draft cannot be edited, so to change one (a new price, say) discard it and create the listing again. Without confirmed: true nothing changes and the draft is described back.
| Name | Required | Description | Default |
|---|---|---|---|
| draft_id | Yes | A draft_id from listing_create or from drafts_awaiting_photos in seller_list_listings. | |
| confirmed | Yes | false: nothing changes, and the result says what would. true: discard it, once the seller has agreed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true and idempotentHint=true, but the description goes further and explains concretely what destruction means: the draft leaves drafts_awaiting_photos, its finish_url stops opening it, and listing_add_photos can no longer complete it. It also documents the dry-run gate ('without confirmed: true nothing changes and the draft is described back'), which is real behavioral context 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?
Three sentences, zero filler, front-loaded with the destructive effects before the constraints and the edit-workaround. Every clause carries distinct information 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?
Even without an output schema, the description explains what the call does, what it irreversibly affects, the account scoping, the confirmation requirement, and the dry-run response. Nothing needed to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the parameter baseline is 3, but the description adds meaning by explaining the confirmed dry-run contract (nothing changes and the draft is echoed back) rather than merely restating the boolean. The draft_id is left to the schema, which already names its sources.
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 (discard) and resource (draft), plus the exact scope: drafts that listing_create saved without photos. It distinguishes itself from siblings by naming listing_add_photos and listing_create directly, so an agent can select it 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 covers when to use it and the alternative path: since a draft can't be edited, the description instructs the agent to discard and recreate when a change (e.g. a new price) is needed. It also states the eligibility constraint (only this account's own connector drafts) and the confirmation prerequisite.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use when the user is selling a large or valuable item (fitness equipment, hot tubs, saunas, golf carts, furniture, appliances), including when also posting to Facebook Marketplace, Craigslist, or OfferUp. Work out which Commonplace category an item belongs to and what it needs before it can be listed (terms as in the server instructions). An exact category slug or name is taken as given; other words are matched. Returns required_questions (exact option strings; other_values_accepted means a value not listed may be given as written), condition_options with condition_shown_as (how each reads in the public title, which never reads worse than Fair: Poor reads Fair), seller_costs (the pickup fee and the transaction fee, added on top of the seller's take-home) and buyer_price_addons (delivery within 100 miles, included in the buyer price). Category drives the pickup fee and so the take-home: resolve it before quoting or listing. ambiguous is true when only a brand was named and its models differ in fees (a brand's own parent category, such as peloton, is never a category to list under), or when the item's own words name a different category from the match; possible_categories then lists the choices, each with its costs, and passing the right one back as item settles it. other_candidates lists nearby categories whose names share a word with the item. Condition is not a required question: it is listing_create's own condition argument, and where the options name a usage band (rides, uses) the grade is by usage alone.
| Name | Required | Description | Default |
|---|---|---|---|
| item | Yes | The item in the seller's own words, e.g. "2021 Peloton Tread". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare a safe read; the description goes far beyond them by detailing the returned fields (required_questions, condition_options/condition_shown_as, seller_costs, buyer_price_addons), the fee/take-home implications of the category, and precise ambiguity semantics (ambiguous, possible_categories, other_candidates). This is rich behavioral disclosure rare in a description.
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?
Every sentence carries information, but the content is packed into one very long paragraph with heavy nested parentheses, so key rules (ambiguity handling, condition semantics) are hard to locate and the piece is not well front-loaded after the usage opener.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description must carry the return contract, and it does so thoroughly, including the condition-vs-required_questions boundary with listing_create. Some nested field detail (e.g. exact shape of seller_costs) remains implicit, keeping it short of perfect.
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% for the single 'item' param, so baseline is 3, but the description adds real meaning: an exact slug/name is taken as given while other words are matched, clarifying how the input is interpreted.
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: work out which category an item belongs to and what it needs before listing, with concrete item types. It does not explicitly name or contrast with a sibling such as catalog_list_categories, so sibling differentiation is left implicit.
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 ('use when the user is selling a large or valuable item...') plus a sequencing rule ('resolve it before quoting or listing') that ties it to the pricing tools. No explicit when-not or alternative named, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use when the user is selling a large or valuable item (fitness equipment, hot tubs, saunas, golf carts, furniture, appliances), including when also posting to Facebook Marketplace, Craigslist, or OfferUp. Call this when the item sells on Facebook Marketplace, Craigslist, OfferUp, or anywhere else. Pass the manage_token that listing_crosslist_draft returned. The listing comes down. No account is required. If it never published, the confirm link stops working.
| Name | Required | Description | Default |
|---|---|---|---|
| manage_token | Yes | The manage_token returned with the draft. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations by disclosing the destructive consequence ('The listing comes down'), the auth profile ('No account is required'), a failure edge case ('If it never published, the confirm link stops working'), and the token provenance from listing_crosslist_draft. These are exactly the behavioral facts an agent cannot derive from destructiveHint/idempotentHint alone.
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?
Short, front-loaded sentences that lead with the usage trigger before the mechanics, with zero filler. It does repeat the Facebook Marketplace / Craigslist / OfferUp list twice, which is minor redundancy in an otherwise tight block.
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, no-output-schema tool, the description covers trigger, dependency, auth, destructive effect, and an edge case, so an agent has everything needed to call it. The reference to a 'confirm link' is left slightly unexplained (who holds it, what it is), which is a small residual 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 coverage is 100% and the single parameter is documented in the schema, so the baseline is 3. The description adds genuine value by stating the token must be the one returned by listing_crosslist_draft, establishing provenance the schema's generic 'returned with the draft' wording does not.
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 ('mark sold') and the exact trigger condition—the item sold on Facebook Marketplace, Craigslist, OfferUp, or anywhere else—plus the concrete effect ('The listing comes down'). This distinguishes it from siblings like seller_remove_listing or seller_relist_listing, which do not carry the 'sold elsewhere' semantics.
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 says when to call it ('Use when the user is selling a large or valuable item... Call this when the item sells on Facebook Marketplace, Craigslist, OfferUp, or anywhere else') and names listing_crosslist_draft as the source of the required token. It does not, however, state when NOT to use it versus seller_remove_listing or seller_relist_listing, so an agent facing an ambiguous removal scenario still has to infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use when the user is selling a large or valuable item (fitness equipment, hot tubs, saunas, golf carts, furniture, appliances), including when also posting to Facebook Marketplace, Craigslist, or OfferUp. What comparable items sell or list for, as low / typical / high prices before delivery (buyers see these plus added_to_buyer_price_usd, in buyer_prices_usd): low is the 25th percentile, typical the median, high the top of where most sit (never below typical). take_home_usd is what a seller is paid when an item sells at each figure. sample_size counts every listing it is based on, sold and past ones included. model narrows it to listings whose titles name a brand, model or year; narrowed_to says whether it did, and model_matches how many listings name it (a range needs 5). basis says whether the range comes from sold items or listings; a narrowed range can differ in basis from the whole category. available: false means too little data for a range. The price the seller asked for on Facebook Marketplace, Craigslist, or OfferUp becomes their take-home on Commonplace. The buyer price includes pickup and delivery.
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | A brand, model or year to narrow to, e.g. "Kettler", "Bike+" or "2022". Matched against listing titles in the category. | |
| category | Yes | A category name or slug, e.g. "hot tubs". |
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 substantial behavioral context beyond that: it explains percentile semantics for low/typical/high, what take_home_usd means, that sample_size spans sold and past listings, that a narrowed range needs at least 5 matches and can differ in basis, and that available:false means insufficient data. Latency, permissions, and rate limits are not covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is front-loaded correctly with the 'Use when' trigger, and most sentences carry real information given the absence of an output schema. However, it is a dense run-on paragraph held together by semicolons and parentheticals, and the Marketplace/Craigslist/OfferUp reference is repeated, which hurts scanability.
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 full burden of documenting the response and does so nearly field by field: low/typical/high, take_home_usd, sample_size, narrowed_to, model_matches, basis, available, buyer_prices_usd, and added_to_buyer_price_usd. An agent can interpret the result without any other source.
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 both parameters are already documented. The description still adds meaning beyond the schema for model: it explains the narrowing is against listing titles, exposes the outcome via narrowed_to and model_matches, and states the 5-match threshold required for a narrowed range. Category itself gets no extra 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 a specific resource and deliverable: comparable sale/list prices for a category, expressed as low/typical/high before delivery, with take-home figures. The framing around take-home vs buyer price implicitly separates it from pricing_quote_payout and pricing_quote_crosslist, though those siblings are never named. Purpose is clear but not explicitly contrasted with alternatives.
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 when-to-use trigger with concrete item types (fitness equipment, hot tubs, saunas, golf carts, furniture, appliances) and the cross-listing scenario (Facebook Marketplace, Craigslist, OfferUp). There is no when-not guidance and no sibling tool is named as an alternative, so the routing value is context-only.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use when the user is selling a large or valuable item (fitness equipment, hot tubs, saunas, golf carts, furniture, appliances), including when also posting to Facebook Marketplace, Craigslist, or OfferUp. The price the seller asked for on Facebook Marketplace, Craigslist, or OfferUp becomes their take-home on Commonplace. The buyer price includes pickup and delivery. Give category and price. price_type defaults to take_home. Pass facebook_buyer_price when the number is what a buyer pays on the other site. ZIP is optional. The result is take_home_usd and buyer_price_usd.
| Name | Required | Description | Default |
|---|---|---|---|
| zip | No | Optional 5-digit pickup ZIP. | |
| category | Yes | A category slug, a category name, or the item words. | |
| price_usd | Yes | ||
| price_type | No | take_home (the default) is what the seller takes home. facebook_buyer_price is what a buyer pays on the other site. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, non-destructive behavior, so the bar is lower. The description adds useful behavioral context beyond them: price_type defaults to take_home, and with no output schema present it names the return fields (take_home_usd, buyer_price_usd). It does not discuss edge cases such as invalid categories.
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 a clear 'Use when' opener, but the Facebook Marketplace/Craigslist/OfferUp list is repeated across sentences and the seller-perspective explanation is verbose, adding some redundancy for the information conveyed.
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 computation tool with no output schema, the description usefully states the two return values and the default behavior of price_type. Combined with the required-parameter guidance ('Give category and price'), it is nearly complete, missing only error/edge-case handling.
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 75%, so the schema already carries most parameter meaning. The description largely restates the schema's price_type semantics ('Pass facebook_buyer_price when the number is what a buyer pays') and adds only the default-value fact ('price_type defaults to take_home'), leaving price_usd undocumented by both.
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 operation (quoting a cross-list price) and clarifies the two resulting numbers (take-home vs buyer price). It distinguishes itself semantically from pricing_quote_payout by centering on cross-listing to other marketplaces, though it never names that sibling directly.
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 triggering context: 'Use when the user is selling a large or valuable item... including when also posting to Facebook Marketplace, Craigslist, or OfferUp.' That is a strong when-to-use signal, but it names no alternative tools and gives no explicit when-not-to-use condition, so the routing is implied rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use when the user is selling a large or valuable item (fitness equipment, hot tubs, saunas, golf carts, furniture, appliances), including when also posting to Facebook Marketplace, Craigslist, or OfferUp. The seller's fee math for a category (terms as in the server instructions). Give exactly one of: desired_payout_usd, a take-home, for the buyer price a new listing shows (the transaction and pickup fees and delivery added on top; the seller is paid exactly the take-home); buyer_sees_usd, a price a buyer pays (a listing's price or an offer), for what the seller takes home at it (delivery, then the transaction fee, then the pickup fee come out); or price_usd, an older listing's asking price, for its take-home. pickup_fee_waived is true when, taking fees out of a price, the pickup fee would exceed what is left after the transaction fee. The price the seller asked for on Facebook Marketplace, Craigslist, or OfferUp becomes their take-home on Commonplace. The buyer price includes pickup and delivery.
| Name | Required | Description | Default |
|---|---|---|---|
| category | Yes | A category name or slug. | |
| price_usd | No | An asking price before delivery on a listing made before September 4 2026, in US dollars. | |
| buyer_sees_usd | No | A price a buyer pays, in US dollars: a listing's buyer price, or an offer. | |
| desired_payout_usd | No | What the seller wants to take home, in US dollars. How every new listing is priced. |
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 and this is clearly a pure computation. The description adds the fee-stack ordering (delivery, then transaction fee, then pickup fee) and the pickup_fee_waived rule, which is useful context, but says nothing about permissions, side effects, or response shape.
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?
Usage is front-loaded, but the body is dense with nested clauses and repeats itself (Facebook Marketplace/Craigslist/OfferUp appear twice, and the take-home framing is restated in the closing two sentences). It is parseable but clearly longer and harder to follow than the underlying four parameters warrant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description carries the burden of describing return values; it hints at pickup_fee_waived and the payout figure but never enumerates the response fields. It also defers essential fee terms to 'the server instructions', which the agent may not have, leaving the quote semantics partly incomplete.
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 semantics beyond the schema: it defines the mutual-exclusion rule ('give exactly one of') and clarifies how each input differs (price_usd = pre-Sept-4-2026 asking price, buyer_sees_usd = a price a buyer pays, desired_payout_usd = target take-home). The schema enforces none of that exclusivity, so this is genuine added value.
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 tool computes a seller's take-home/payout math for a category, and the description spells out the three input modes (desired_payout_usd, buyer_sees_usd, price_usd), which is a fairly specific verb+resource. It never names the adjacent pricing tools (pricing_quote_crosslist, pricing_get_guide), so the agent must infer the boundary from the mode list rather than an explicit distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The opening sentence gives a concrete when-to-use trigger (selling a large/valuable item, including crosslisting to Facebook Marketplace/Craigslist/OfferUp), and it later imposes the 'give exactly one of' rule. It offers no explicit when-not condition or named alternative among sibling pricing tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The seller's own listings - the same list Your Listings shows - with each one's status (Active; In review; Reserved; Sold; Inactive, which seller_relist_listing can bring back; Removed, taken down by the seller, shown only with include_removed and never back), pricing_basis (take_home: seller_update_listing's price_usd sets take_home_usd; asking_price, older listings: it sets asking_usd, null on one lifted to its floor), take_home_usd, buyer_price_usd, the transaction and pickup fees, and link. Removed listings are left out unless include_removed is true. Drafts saved without photos are not listings yet; they are returned separately in drafts_awaiting_photos, each with its finish link. A draft only ever lacks photos: with one, a listing publishes.
| Name | Required | Description | Default |
|---|---|---|---|
| include_sold | No | Include sold items (default false). | |
| include_removed | No | Include listings the seller took down, shown with status Removed (default false). A removed listing cannot come back. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly and non-destructive. The description adds substantive behavior: removed listings excluded unless include_removed, drafts returned separately in drafts_awaiting_photos, and status semantics (Removed never comes back vs Inactive recoverable). This goes well beyond 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 single dense sentence tries to pack status taxonomy, pricing basis, and draft handling together; it's front-loaded with the core purpose, but the wording is convoluted and hard to parse (e.g., 'never back', 'null on one lifted to its floor'). Appropriate length but poor structure.
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 read-only list tool with no output schema, the description gives a solid picture of return content (status, pricing_basis, fees, link, plus drafts_awaiting_photos) and filter behavior. The unexplained include_sold and the muddy pricing-basis sentence are minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters are documented there. The description reiterates include_removed's effect but doesn't add syntax or nuance beyond the schema; include_sold is not discussed in the description despite being a param. 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?
Clearly states it returns the seller's own listings with per-listing status, pricing basis, fees, and link. Distinguishes from catalog_search_listings implicitly (this is 'the seller's own'), but doesn't explicitly name sibling alternatives like catalog_get_listing or seller_list_sales.
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: 'the same list Your Listings shows' and the include_removed explanation give context, but there's no explicit when-to-use/when-not-to-use guidance or named alternatives (e.g., use catalog_search_listings for the public catalog).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Offers buyers have made on the seller's own listings, in PAYOUTS only: what the seller gets if they accept, what they get at their current price, the least a counter can pay them, and what any counter or agreed deal pays them. Never quote buyer prices to the seller. Buyers are shown by first name and last initial; their contact details are never available.
| Name | Required | Description | Default |
|---|---|---|---|
| include_closed | No | Include accepted, declined and expired offers (default false: only ones still open). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish this as a safe read; the description adds genuinely non-obvious behavior: amounts are payout-side only, buyer prices must never be surfaced, and buyers appear as first name plus last initial with no contact details. That is real disclosure beyond structured fields, though nothing is said about ordering, volume, 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?
Two sentences, front-loaded with the scope before the payout breakdown and the privacy rules. The middle clause — four parallel 'what the seller gets...' phrases — is dense but each item carries distinct meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only single-parameter list tool with no output schema, the description covers the critical domain hazards (payout framing, buyer-price suppression, identity masking) that an agent would otherwise get wrong. Only secondary details like ordering or result size are absent.
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 optional include_closed flag is fully documented in the schema, including its default. The description adds no parameter-level information, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States the resource precisely — 'offers buyers have made on the seller's own listings' — with the seller-side scope made explicit, which separates it from any buyer-facing offer lookups. It does not name seller_respond_offer as the action counterpart, so the distinction is implied 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 'in PAYOUTS only' framing and the 'never quote buyer prices to the seller' rule govern how to use the output, which is useful usage context. However, there is no explicit guidance on when to call this versus seller_respond_offer or seller_list_sales, so tool-selection guidance is left implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Orders on the seller's items: order number, status, inspection result, the payout on each and the pickup window. Commonplace pays sellers at pickup, after inspection, by payment link. This system does not record whether a payout was actually sent, so payout_sent is always null here.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real domain behavior beyond that: payouts happen at pickup after inspection via payment link, and payout_sent is always null because the system never records whether a payout was sent. That caveat prevents the agent from misreading a null field as missing data.
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 field inventory in the first sentence, then uses two short sentences to explain payout mechanics and the null-field caveat. Every sentence earns its place; slightly 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?
With no parameters, no output schema, and annotations covering the safety profile, the description carries the remaining burden well by listing returned fields and disclosing the payout_sent caveat. Pagination or result ordering is unaddressed, which keeps it from a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the schema has nothing to document and the baseline is 4. Nothing in the description needs to compensate for parameter gaps.
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 resource (orders on the seller's items) and enumerates the returned fields (order number, status, inspection result, payout, pickup window), so an agent knows exactly what this returns. It does not explicitly name the sibling it is not (seller_list_listings, seller_list_offers), so it falls just 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?
There is no explicit when-to-use or when-not-to-use guidance and no alternatives are named. The purpose implies it is for reviewing one's sales, but the agent must infer that against seller_list_listings and seller_list_offers with no help.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Put one of the seller's own inactive listings back on the marketplace. Only an inactive listing can be relisted. Requires confirmed: true.
| Name | Required | Description | Default |
|---|---|---|---|
| confirmed | Yes | false: nothing changes, and the result says what would. true: do it, once the seller has agreed. | |
| listing_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the write, idempotent, non-destructive, open-world profile, so the bar is lower. The description adds genuinely new behavior: the listing must currently be inactive, and the confirmed flag gates execution, which is state and safety context not encoded in 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, front-loaded sentences with the action and precondition leading. "Requires confirmed: true" is somewhat redundant with the required array and the confirmed parameter's own description, which is a minor 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 a state-changing tool with no output schema and 50% parameter documentation, the description covers the precondition and the dry-run gate but says nothing about the failure mode when the listing is not inactive, or what data (price, photos) is restored on relist. Adequate but with clear gaps.
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%: confirmed is well documented in the schema, but listing_id is undocumented there. The description compensates by qualifying listing_id as one the seller owns and that must be inactive, adding real semantic constraints beyond the integer bounds. The confirmed sentence largely restates the schema, so it is not a full 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?
The description names a specific verb (relist), the resource (one of the seller's own listings), and the target state (back on the marketplace from inactive). This clearly separates it from listing_create and seller_update_listing, though it never explicitly names an alternative sibling, which keeps it just 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?
"Only an inactive listing can be relisted" gives a concrete precondition for when the tool applies, which is real usage context. It does not, however, route the agent away from alternatives (e.g., use listing_create if the listing is gone, or listing_discard_draft for drafts), so it stops short of the explicit when/when-not of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Take one of the seller's own listings off the marketplace. Refused while an order is active on it - that needs the support team. Requires confirmed: true after the seller agrees to remove that specific item.
| Name | Required | Description | Default |
|---|---|---|---|
| confirmed | Yes | false: nothing changes, and the result says what would. true: do it, once the seller has agreed. | |
| listing_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructive=true, idempotent=true, readOnly=false and openWorld=true, so the safety profile is covered. The description adds genuinely new behavior: a hard refusal while an order is active and a consent precondition tied to the specific item. It doesn't say whether the listing's photos/offers are also discarded, which keeps it from a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the action, then the refusal boundary, then the confirmation requirement. Every sentence carries distinct, necessary information; 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 destructive two-parameter mutation with no output schema, the definition covers the action, the refusal case, the alternative (support) and the confirmation protocol. Minor gaps remain: the ID's provenance and whether the removal is recoverable, though destructiveHint already signals irreversibility.
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%: 'confirmed' is thoroughly documented in the schema itself, while 'listing_id' carries only integer bounds. The description partially compensates by implying the ID must reference the seller's own listing (ownership constraint), but it doesn't say where to obtain that ID (e.g. seller_list_listings) or what happens on an invalid/non-owned ID.
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?
Sharp specific verb + resource scoped to ownership: 'Take one of the seller's own listings off the marketplace.' That scope plus the active-order refusal separates it from neighbors like seller_relist_listing or mark_sold_elsewhere, though no sibling is named explicitly, 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 an explicit when-not condition ('Refused while an order is active on it') and points to the alternative channel ('that needs the support team', i.e. support_create_ticket). It also states the precondition for proceeding ('Requires confirmed: true after the seller agrees to remove that specific item'). Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Accept, counter or decline an open offer on one of the seller's own listings. Sellers work in PAYOUTS only: a counter is the amount the seller wants to get (counter_payout_usd), and Commonplace sets the buyer price that pays it. Never quote buyer prices to the seller. IMPORTANT consequences: accepting starts the sale and updates the listing to match, and a counter updates the listing for every buyer, not only this one. Requires confirmed: true after the seller agrees.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | ||
| offer_id | Yes | ||
| confirmed | Yes | false: nothing changes, and the result says what would. true: do it, once the seller has agreed. | |
| counter_payout_usd | No | Required for a counter. What the seller wants to get, in US dollars. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the destructiveHint/readOnlyHint annotations: accepting starts the sale and updates the listing, and a counter mutates the listing for every buyer, not just this one. It also discloses the payout-only pricing model and the meaning of the confirmation gate, which are exactly the consequences 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 action and resource, then the payout-model caveat, then the consequences, then the confirmation rule — every sentence carries decision-relevant information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive mutation tool with no output schema, it covers safety consequences, pricing semantics, and confirmation adequately. It stops short of stating what happens to competing offers when one is accepted, which is a real open question for the 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?
With 50% schema coverage, the description adds meaningful semantics: counter_payout_usd is the seller's net payout and Commonplace derives the buyer price, and `confirmed` gates real mutation. The enum values for `action` are self-explanatory in the schema, so full marks aren't warranted.
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 specific verbs (accept, counter, decline) and the resource (an open offer on the seller's own listing), which cleanly separates it from seller_list_offers (read) and listing_update (edit). An agent can pick this tool 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?
Explains the operating context (seller works in PAYOUTS, counter is expressed as counter_payout_usd) and the prerequisite that `confirmed: true` is only sent after the seller agrees. It does not explicitly name alternatives or say when not to use it, but the preconditions are clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Edit one of the seller's own listings the way the website's Edit listing does: title, price (price_usd), lowest_acceptable_usd, category, condition, pickup location and photos. Give only what changes. Without confirmed: true nothing changes: the result lists the change and, when the price or category moves, would_result_in (take-home, buyer price, fees). What price_usd and lowest_acceptable_usd mean follows the listing's pricing_basis in seller_list_listings. take_home (every listing made from Sept 4 2026 on): price_usd is what the seller takes home, and our transaction and pickup fees and the delivery are added on top for buyers; lowest_acceptable_usd is the least they take home. asking_price (older listings): price_usd is the asking price before delivery (asking_usd), the take-home is that less our fees, and lowest_acceptable_usd is an asking price too. The platform adds the condition and city to the title, as it does at publish, and rebuilds them when the title, condition or pickup location changes; the preview's public_title is the exact result, and the listing's link does not change. photos is the whole ordered list after the edit, the first being the cover. A reserved or sold listing cannot be edited, and the description is not edited here (support corrects it).
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | ||
| photos | No | The listing's photos after the edit, in order, the first being the cover. "existing:N" keeps the photo now at index N (catalog_get_listing's photo_urls end in /N); an https image URL or a data:image URL adds one (at most 8 new per edit). Leave a photo out to remove it; at least one must remain. "file:N" places the Nth of photo_files, the photos attached in the chat. | |
| category | No | A category slug from catalog_list_categories or listing_resolve_category. It changes the fees and what buyers pay, so preview first. | |
| condition | No | One of the category's condition_options from listing_resolve_category. | |
| confirmed | Yes | false: nothing changes, and the result says what would. true: do it, once the seller has agreed. | |
| price_usd | No | New price in US dollars, in the listing's pricing_basis: its take-home, or on an older listing its asking price. | |
| listing_id | Yes | ||
| photo_files | No | Photos the seller attached in the chat. The chat app fills these in (each a download_url and file_id); never write one by hand. They get the same checks as photo_urls. Place them with "file:N" in photos ("file:0" first makes it the cover); any not placed are added after the photos. | |
| pickup_location | No | Where the item is now: "City, ST", or a full address that contains it. A ZIP alone cannot move where the listing says it is. | |
| lowest_acceptable_usd | No | The auto-accept floor, in the listing's pricing_basis: the least the seller takes home, or on an older listing the lowest asking price. Offers that reach it are accepted automatically. 0 removes it. It cannot be above price_usd. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructive=true and idempotent=true, but the description adds substantial behavior beyond them: the confirmed:true gating, the would_result_in preview contents (take-home, buyer price, fees), automatic title rebuilds on title/condition/location changes, the immutable listing link, and the fact that photos are the whole ordered list with the first as cover. This is exactly the extra behavioral context annotations cannot 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?
Front-loaded with purpose and editing constraints before the pricing-basis detail. It is long and the pricing-basis paragraph is dense, but each sentence carries operational information an agent needs (confirmation gating, preview output, auto-title behavior), so little 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 10-parameter mutation tool with no output schema and destructive semantics, the description supplies the confirmation workflow, preview contents, pricing-basis interpretation, field-update semantics and explicit non-editable cases. Nothing essential for a correct call 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 coverage is 80% (baseline 3), but the description adds real meaning: it resolves the ambiguous price_usd and lowest_acceptable_usd by tying them to the listing's pricing_basis (take_home vs asking_price), which the schema only hints at, and clarifies photos ordering/cover semantics. This goes beyond duplicating 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 (edit) plus resource (one of the seller's own listings) and enumerates exactly which fields are editable. 'Give only what changes' further pins it as a partial-field update, distinguishing it from siblings like listing_add_photos or seller_relist_listing without the agent needing to open 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?
Clear when-to-use context: preview with confirmed:false, then commit with confirmed:true once the seller agrees. It also states exclusions — a reserved or sold listing cannot be edited and the description is not edited here (support corrects it). It stops short of explicitly routing to alternative siblings (e.g. photo-only additions), so it is strong rather than exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Hand a problem to the Commonplace support team. A teammate follows up by text or email using the contact details on the account. Use it for things no tool can do: order changes, pickup problems, payout questions, disputes. Requires confirmed: true. Limited to a few per day per account.
| Name | Required | Description | Default |
|---|---|---|---|
| summary | Yes | What the seller needs, in their words. | |
| confirmed | Yes | false: nothing changes, and the result says what would. true: do it, once the seller has agreed. | |
| listing_id | No | ||
| order_number | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds real context beyond the annotations: a teammate follows up by text or email using account contact details, and there is a per-account daily rate limit. The annotations cover the safety profile (write, idempotent, non-destructive), so the remaining burden was rate limits and outcome, both addressed.
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, front-loaded with the action and the outcome, then usage, then the confirmation precondition, then the rate limit. No sentence is redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and an open-world write, the description still makes the outcome predictable (human follow-up by text/email) and flags the confirmed and rate-limit constraints. Only the association of listing_id/order_number to a ticket is left unaddressed.
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 does add meaning for 'confirmed' by stating it must be true to proceed, and implies that repeat calls are limited. However, it says nothing about how listing_id or order_number should be supplied, leaving those two undocumented in both places.
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 ('hand a problem to the Commonplace support team') and clarifies the human follow-up channel. It distinguishes itself from the sibling support_search_help by scoping to 'things no tool can do,' so an agent can tell the two apart without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete when-to-use examples (order changes, pickup problems, payout questions, disputes) and an implicit exclusion ('things no tool can do'). It does not explicitly name support_search_help as the alternative for self-serve help, which is the one missing routing cue.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Answer a question about how Commonplace works. platform_policy states the current rules on the topics the question is about (delivery, payment, inspection and returns, warranty, offers, selling), from the live settings. answers are the closest published help articles, each marked truncated when cut short (the whole answer is at help_center_url). loosely_related shares some words with the question (it can still hold the answer, so read it) and does not count toward found, but can still hold the answer in other words (a subscription, asked about as a membership). found is true when platform_policy or answers has something. Where an article disagrees with platform_policy, platform_policy is current.
| Name | Required | Description | Default |
|---|---|---|---|
| question | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover the safety profile (readOnly, non-destructive, closed-world), and with no output schema the description carries the full return-value burden — it explains found, truncated, help_center_url, the loosely_related exclusion from found, and the precedence rule that platform_policy beats published articles. That precedence rule is genuinely non-obvious behavioral context an agent could not infer.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded, but the rest is a run-on paragraph that repeats the same idea twice ('it can still hold the answer, so read it' and 'can still hold the answer in other words') and mixes field definitions with precedence rules. It is understandable but does not justify its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does the essential work of defining every response field and the platform_policy-vs-article conflict rule, which is what an agent needs to consume the result correctly. The gap is routing: nothing tells the agent when to escalate to support_create_ticket instead.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is one parameter with 0% schema description coverage, so the description must compensate; it implies the input is a natural-language question about platform behavior. It does not mention the 3–300 character bounds or anything about phrasing, so it only partially fills the gap.
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 opening sentence gives a specific verb and resource: answer a question about how Commonplace works, which is unambiguously the help-center search tool and distinct from support_create_ticket. It stops short of naming siblings or stating the scope boundaries that would make it 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?
Usage is implied by 'Answer a question about how Commonplace works,' and there is useful guidance on reading loosely_related and trusting platform_policy over articles. There is no explicit when-to-use-this-vs-alternative guidance, and support_create_ticket is never mentioned despite being the obvious sibling for unresolved questions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
seller_respond_offer2 fields changedInput schema / properties / counter_payout_usdAdded value: +{
+ "description": "Required for a counter. What the seller wants to get, in US dollars.",
+ "maximum": 1000000,
+ "minimum": 1,
+ "type": "number"
+}Input schema / properties / counter_usdRemoved value: -{
- "description": "Required for a counter. Buyer-facing price in US dollars.",
- "maximum": 1000000,
- "minimum": 1,
- "type": "number"
-}account_get_profilecatalog_get_listingcatalog_list_categoriescatalog_search_listingsdelivery_quote_listinglisting_add_photoslisting_createlisting_crosslist_draftlisting_discard_draftlisting_resolve_categorymark_sold_elsewherepricing_get_guidepricing_quote_crosslistpricing_quote_payoutseller_list_listingsseller_list_offersseller_list_salesseller_relist_listingseller_remove_listingseller_respond_offerseller_update_listingsupport_create_ticketsupport_search_helpAI resale manager. Photograph an item, AI writes the listing, publish a sale page, manage pickups.
Find free stuff near any US ZIP, priced for resale. Live listings, resale estimates, alerts.
Let your agent buy and sell physical goods, with escrow and shipping.
Buy and sell with Bitcoin, Monero or Pirate Chain. Listings, Want Ads, offers, escrow.
Add one secure layer between your agents and this server.
