Original art from galleries and artists: search, details, delivered prices and checkout links.
Scored across 10 tools
Each tool maps to a distinct step in the buyer journey: search, artwork detail, availability re-check, delivered quote, checkout, order status, claim, and the three search-alert operations. The descriptions explicitly draw boundaries between the easily confused pair (search_artworks, check_availability, get_delivered_quote), noting when a call is unnecessary because checkout re-verifies. No two tools overlap in purpose.
All ten names follow a strict snake_case verb_noun pattern (search_artworks, get_artwork, save_search_alert, start_checkout). Verb choice is predictable and resource-oriented, and the save/get/cancel triplet for search alerts reinforces the convention rather than breaking it.
Ten tools is well within the sweet spot for a buyer-facing marketplace agent. Every tool earns its place: three for alerts, three for discovery and detail, two for pricing/checkout, two for post-purchase. Nothing feels padded or missing.
The purchase lifecycle is fully covered end to end: discovery, detail, availability, delivered cost, checkout, order tracking, claims/cancellation, and alert management with full CRUD. Minor gaps exist—no seller/profile lookup, no order history listing, and no way to retrieve saved alerts in bulk—but agents can work around these via the provided IDs and tokens.
Use this when a buyer wants to stop an alert for new works. Nothing more is sent, and the saved words, filters and address are erased. Needs the search_alert_id and manage_token save_search_alert gave; a buyer can also stop it from any alert e-mail in one click.
| Name | Required | Description | Default |
|---|---|---|---|
| manage_token | Yes | The manage_token save_search_alert gave. | |
| search_alert_id | Yes | The search_alert_id save_search_alert gave. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes beyond the destructiveHint=true annotation by specifying exactly what is erased: the saved words, filters and address, plus that nothing further is sent. It also discloses the credential requirement (search_alert_id and manage_token from save_search_alert) and an alternate cancellation route, which is real context an agent cannot get from 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 tight sentences, front-loaded with the trigger condition, then consequences, then prerequisites. No filler; each sentence contributes a distinct fact.
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?
Covers the trigger, the destruction scope, the credentials and the alternate path, which is sufficient for a two-parameter mutation with full annotations and no output schema. Only minor gap is behavior on an already-cancelled alert, which idempotentHint=true largely covers.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and both parameter descriptions already state they come from save_search_alert, so the description's restatement of that provenance adds no new meaning. Baseline 3 applies since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('stop') and resource ('an alert for new works'), which is unambiguous next to cancel_purchase or get_search_alert. It doesn't explicitly name a sibling to contrast with, so the differentiation is inferred from the resource name 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?
'Use this when a buyer wants to stop an alert for new works' gives a clear triggering condition, and the one-click e-mail path is named as an alternative channel. There is no explicit when-not guidance, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when time has passed since a search or a work’s detail answered — the buyer came back later, or is weighing several works — to re-check whether specific impressions can still be bought before offering them. Each work here is unique or from a small edition, so an impression can sell at any time: never offer one as available from an old answer. A search’s offers and get_artwork say what can be bought as they answer, and the checkout checks again itself, so no call is needed between them and the checkout.
| Name | Required | Description | Default |
|---|---|---|---|
| listing_ids | Yes | listing_id values from get_artwork. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, and closed-world. The description adds valuable domain behavior: works are unique/small-edition, so availability can change at any time and stale answers should never be trusted. It doesn't describe the response shape, but the behavioral context is strong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the trigger condition before the rationale and the exclusions. The middle sentence is slightly verbose but every clause carries meaning about the re-check requirement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, no-output-schema read tool, the description covers trigger, rationale, and when to skip it. Only the return semantics (what 'available' looks like) are left implicit, which is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and documents listing_ids (including its get_artwork provenance and 1-50 bounds). The description adds no format or batching semantics beyond what the schema provides, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource: re-check whether specific impressions can still be bought. It clearly distinguishes the operation from merely reading an old answer, though the term 'impressions' is domain jargon that slightly muddies the mapping to listing_ids.
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 states when to use (time has passed since a search or get_artwork answer, buyer returned later or weighing several works) and when not to (a search's offers and get_artwork are current as they answer, and checkout re-checks itself, so no call is needed in between). This is a model of when/when-not guidance with sibling references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when someone wants the full facts about one work before deciding: what it is, its size, how it looks, what delivery costs and when it ships, whether it can be returned, who made it, and what Fold verified about the seller. Full detail for one artwork: attribution, medium, dimensions, edition structure, provenance, seller, and every individual impression that can be bought with its own price and availability. A numbered edition has one entry per impression — including artist proofs (AP), printer proofs (PP), and the bon à tirer (BAT), which are separate objects from the numbered run and usually priced differently. Each entry in attributes says who stands behind it (seller_stated, fold_derived or fold_verified), and a null means unspecified rather than estimated. Also returns image URLs to show the buyer. A signed URL is TEMPORARY: honour its expires_at and re-fetch rather than caching or redistributing it. An image marked permanent is one of the work’s public images, with no expiry: a clean display copy, or, where it also says preview, a reduced copy watermarked by Fold. Use this before presenting a work to a buyer, and quote the impression label exactly as given. Its public images, up to 3, also come as small pictures attached after the answer, so you can see how it looks.
| Name | Required | Description | Default |
|---|---|---|---|
| artwork_id | Yes | artwork_id from search_artworks. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the read-only/idempotent annotations, it discloses important behavior: signed image URLs are temporary and must not be cached or redistributed; permanent images may be clean or watermarked preview copies; null attribute values mean unspecified rather than estimated; AP/PP/BAT impressions are separate objects and usually priced differently. This is exactly the extra context an agent needs before calling and handling output.
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 opening sentence's list of facts is largely repeated by the second sentence ('Full detail for one artwork: attribution, medium, dimensions...'), adding length without new information. The image-URL guidance earns its place, but the overall description 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 carries the full burden and does so thoroughly: it explains the return structure at a conceptual level, attributes semantics, edition impression handling, image URL expiry rules, and the attached image previews. An agent has enough information to call it and interpret the result correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents artwork_id at 100% coverage and even states it comes from search_artworks. The description adds no further syntax, format, or identifier semantics beyond that, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('full detail for one artwork') and enumerates the returned facets (attribution, medium, dimensions, editions, provenance, seller, images). It is clearly distinguishable from search_artworks by emphasizing single-work depth, and the artwork_id schema reference reinforces the retrieval relationship.
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 usage context: 'Use this when someone wants the full facts about one work before deciding' and 'Use this before presenting a work to a buyer.' It does not explicitly name alternatives or when-not-to-use cases, but the intended moment is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when a buyer asks what a work will cost delivered to them and when it would arrive. Given one listing_id and a US destination (a five-digit ZIP code, and the state if known), it answers with the price, the seller’s delivery charge, an ESTIMATE of sales tax from Fold’s tax engine for that ZIP code, the total, the date the seller says it ships by and the arrival window their transit estimate gives, the returns that apply, the policy links and how to check out. Read-only: nothing is opened or reserved. Checkout calculates the exact tax from the full address before the buyer pays. Fold delivers only to the 50 US states and DC.
| Name | Required | Description | Default |
|---|---|---|---|
| listing_id | Yes | A listing_id from get_artwork. | |
| destination | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial context beyond annotations: tax is an ESTIMATE, checkout uses full address for exact tax, nothing is opened or reserved, and delivery is limited to the 50 US states plus DC. These are key behavioral constraints for an agent.
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 use case, then covers outputs, estimate caveat, read-only status, and geographic limits. Although dense, every clause adds decision-relevant information and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description appropriately explains the returned quote fields, estimate caveat, policy/checkout links, and geographic restriction. Combined with annotations, it is complete enough for an agent to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%, and the description adds useful meaning: destination is a US five-digit ZIP and state if known, and listing_id references an artwork/listing. It does not fully compensate for all nested schema gaps, but does enough to guide correct input.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb-like purpose—estimate delivered price and arrival for a work—and enumerates the returned quote components. It also distinguishes itself from purchase/checkout flows by saying it is read-only and that checkout calculates exact tax.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a clear triggering condition: use when a buyer asks delivered cost and arrival timing. It also clarifies the checkout alternative for exact tax and notes the read-only, non-reserving behavior, so the agent knows when this tool is appropriate versus purchase-related siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when a buyer asks where their order is or what they can still claim. With the token from the order page’s address, or the order reference from the confirmation e-mail and the e-mail address the buyer gave at checkout, it answers with the order’s status, the tracking the seller recorded, and each return or claim window with when it closes. An order is shown only to whoever proves they placed it; an unknown order and a wrong proof get the same answer.
| Name | Required | Description | Default |
|---|---|---|---|
| buyer_email | No | The e-mail address the buyer gave at checkout. Send with order_reference. | |
| order_token | No | The token in the order page’s address, from the confirmation e-mail: /order/<token>. | |
| order_reference | No | The order reference printed in the confirmation e-mail. Send with buyer_email. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, it discloses the authorization model ('shown only to whoever proves they placed it') and a critical anti-enumeration behavior: an unknown order and wrong proof return the same answer. That tells the agent how to interpret an ambiguous response without needing to guess.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the usage trigger before the mechanics, and every clause carries information. The middle sentence is dense and slightly run-on, but nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by enumerating the response contents and their granularity (windows with closing dates). Combined with the credential and disclosure behavior, an agent has everything needed to call it and 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?
Schema coverage is 100%, so per-parameter meaning is already handled. The description adds value by presenting the two parameters as an either/or credential scheme (token alone, or reference plus e-mail), which is not stated as a single rule anywhere in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb+resource and names the actual buyer question it answers ('where their order is or what they can still claim'), then enumerates the returned content: status, seller-recorded tracking, and each return/claim window with its closing date. This clearly separates it from siblings like get_purchase or check_availability.
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 clause gives an explicit trigger condition (a buyer asking about order location or remaining claim rights) and specifies the two credential paths, which functions as a usage precondition. No sibling alternative or when-not-to-use case is named, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when a buyer asks about an alert for new works they saved: whether it is waiting for them to confirm it, active or ended, what it watches, when it last sent works and when it ends. Needs the search_alert_id and manage_token save_search_alert gave.
| Name | Required | Description | Default |
|---|---|---|---|
| manage_token | Yes | The manage_token save_search_alert gave. | |
| search_alert_id | Yes | The search_alert_id save_search_alert gave. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real context beyond them: the call requires the manage_token that save_search_alert issued, meaning access is capability-gated by a prior write call. It does not discuss error behavior when the token is stale, which would have pushed this higher.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler: the usage trigger comes first, followed by the concrete information the call yields and the required inputs. Every clause earns its place and nothing is repeated verbatim.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, and the description compensates by enumerating the alert attributes the agent will learn, plus where the credentials come from. For a two-parameter read-only tool this is nearly complete; only edge behavior when the token or alert no longer exists is 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 description coverage is 100% and both properties are documented there, including the same provenance note ('save_search_alert gave'). The description's restatement of the two required parameters adds no syntax, format, or constraint detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description enumerates exactly what the tool reports about a saved alert (pending confirmation, active/ended, what it watches, last sent, end date), which makes the read operation on the search-alert resource unambiguous and separable from save_search_alert and cancel_search_alert. It stops short of an explicit 'retrieves/reads' verb, relying on the title and field enumeration to convey the action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a concrete trigger: 'Use this when a buyer asks about an alert for new works they saved.' It does not state when-not to use it or name alternatives (e.g. cancel_search_alert for changing state), so the agent must infer the boundaries from sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when a buyer wants to return a work or report a problem with an order: damage or a difference from the description on arrival, non-delivery, a doubt about authenticity or title, an agent purchase they did not authorise, cancelling before dispatch, or a 30-day return. It checks the ground against the Returns policy’s window for this order, records the request for a person at Fold, and answers with a link for sending photographs. It refunds nothing: a person at Fold decides every request and replies by e-mail. Needs the same proof as get_order_status.
| Name | Required | Description | Default |
|---|---|---|---|
| ground | Yes | The ground, as Returns §2 names it. | |
| buyer_email | No | The e-mail address the buyer gave at checkout. Send with order_reference. | |
| description | No | What went wrong, in the buyer’s words. | |
| order_token | No | The token in the order page’s address, from the confirmation e-mail: /order/<token>. | |
| order_reference | No | The order reference printed in the confirmation e-mail. Send with buyer_email. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description discloses the real behavioural profile: it checks the Returns policy window, records the request for a human, returns a photo-upload link, and crucially 'refunds nothing' because a person decides and replies by e-mail. That is exactly the side-effect and expectation-setting 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 the trigger ('Use this when...') followed by the ground list, then the behaviour, then the limitation. The ground enumeration is long but each item earns its place; the second half is tight and every sentence carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description correctly explains the response (a link for sending photographs) and the follow-up path (human review, e-mail reply). Combined with annotations covering mutation and idempotency, an agent has enough to call this correctly; only the cancel_purchase overlap remains 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 description coverage is 100%, with the enum ground values and the order_token/buyer_email pairings already documented in the schema, so the baseline is 3. The description adds only a light cross-reference ('Needs the same proof as get_order_status') and the fact that grounds follow Returns §2; it does not add format or selection guidance beyond 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 and resource ('open a claim / return a work') and enumerates the exact grounds it handles, so an agent can map a buyer complaint to this tool without opening the schema. It also distinguishes itself from siblings by name ('Needs the same proof as get_order_status'), anchoring it against the other order tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit, concrete when-to-use triggers (damage, non-delivery, authenticity doubt, unauthorised agent purchase, cancellation before dispatch, 30-day return) and states the outcome. It does not, however, resolve the overlap with the sibling cancel_purchase, since 'cancelling before dispatch' is listed as a ground here without saying which tool should win.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when a buyer wants to hear about works listed later that match what they are looking for. It saves the search — the buyer’s words in query and the same filters as search_artworks — and tells the buyer by e-mail, or your own system by webhook, when a work that matches it is listed: only works that meet everything asked, never near matches, at most one alert a day, for 180 days. An e-mail alert starts only when the buyer confirms it from the one e-mail Fold sends to ask; ask the buyer before giving Fold their address. Every alert e-mail has one-click unsubscribe. A webhook alert starts once webhook_url answers a signed verification event by echoing its challenge. Works flagged as mature content are left out unless include_mature is true, which only the buyer’s own request should set. Answers with search_alert_id and manage_token, shown once: get_search_alert reads the alert and cancel_search_alert ends it.
| Name | Required | Description | Default |
|---|---|---|---|
| wall | No | Only works whose size suits this wall, as search_artworks’ wall reads it. | |
| No | The buyer’s e-mail address, which they gave for this alert. Fold sends it one e-mail to confirm, and nothing else until they do. | ||
| query | No | What the buyer is looking for, in their words, as for search_artworks. | |
| style | No | Any of these styles. | |
| colors | No | Every one of these among the colours the seller confirmed for the work. | |
| framed | No | Framed (true) or unframed (false), as the seller stated. | |
| medium | No | Any of these media; a family such as painting or print includes its members. | |
| signed | No | Signed by the artist, as the seller stated. | |
| edition | No | unique: one of a kind; edition: one impression of an edition. | |
| subject | No | Any of these subjects. | |
| ships_to | No | Where the buyer wants it delivered. Fold delivers to the 50 US states and DC. | |
| orientation | No | Any of: portrait (taller than wide), landscape (wider than tall), square. | |
| webhook_url | No | Your https endpoint for search_alert.new_works events, signed as Standard Webhooks specifies. It must echo the verification event’s data.challenge. | |
| max_width_in | No | Width at most this, in inches. | |
| min_width_in | No | Width at least this, in inches. | |
| max_height_in | No | Height at most this, in inches. | |
| max_price_usd | No | Highest acceptable price, in US dollars. | |
| min_height_in | No | Height at least this, in inches. | |
| min_price_usd | No | Lowest acceptable price, in US dollars. | |
| ready_to_hang | No | Ready to hang, as the seller stated. | |
| include_mature | No | Also announce works their sellers flagged as mature content. Only when the buyer asked. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish a non-read-only, open-world, non-idempotent, non-destructive mutation. Beyond that, the description discloses the exact-match-only behavior, a one-alert-per-day cap over 180 days, the e-mail double-opt-in confirmation flow, one-click unsubscribe, the signed webhook verification handshake, mature-content exclusion, and that manage_token is shown only once — all material facts an agent could not infer from 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 trigger is front-loaded in the first sentence and every subsequent clause carries operational detail, so the length is justified for a 21-parameter tool with no output schema. It is dense and semi-colon-heavy, and some points duplicate schema descriptions, but there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex mutation with 21 parameters and no output schema, the description covers the prerequisites (buyer consent, webhook verification), the alert lifecycle (daily cap, 180 days, unsubscribe), the mature-content gate, and the return values search_alert_id and manage_token shown once. An agent has enough to decide to call it and what to expect back.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema documents each of the 21 parameters, and the description largely mirrors it for email, webhook_url, and include_mature. It still adds useful aggregate semantics the schema does not: query is the buyer's own words, the filters are the same as search_artworks, and a match must satisfy everything asked rather than near matches.
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 — saving a search that alerts on newly listed works — and names the exact trigger condition (a buyer wants to hear about works listed later). It distinguishes itself from search_artworks by reusing its filters but explaining the alert is for future listings, and it names the sibling tools get_search_alert and cancel_search_alert.
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 use it ('when a buyer wants to hear about works listed later') and how it differs from simply searching with search_artworks. It also gives prerequisites — ask the buyer before giving Fold their address, only set include_mature when the buyer asked — and routes follow-up work to get_search_alert and cancel_search_alert.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when someone wants to find original paintings, prints, photographs or sculpture from independent artists: by subject, style, colour, size or budget; for a particular wall; or like a work or a photo they have. It returns only works that meet everything asked for, each with what it met. near_matches come apart, each saying what it misses or what its seller left unsaid: a blank fact is unknown, never a no. Write the request in words ("a large blue abstract painting under $2,000"; misspellings, and Spanish, Portuguese, French, Italian and German, are read) or send filters — min_price_usd, max_price_usd, orientation, subject, style, medium, colors, min_height_in, max_height_in, min_width_in, max_width_in, ships_to, framed, ready_to_hang, signed, edition — and a filter wins over the words. applied_filters lists every constraint and where it came from; understood says how each word was read (read_as, corrected); correct a misreading with a filter. A word about the work that names no constraint must appear in its own words to match ("lighthouse"). Words of mood ("calm") and of where it will hang ("hallway") only order the results; "to hang" and "a gift" are not used. A place it ships to, with its state or ZIP, is read as ships_to. fold_derived marks Fold’s reading of the seller’s words. This catalogue CANNOT be filtered by authenticity or provenance strength: Fold verifies sellers, not works (see _verification). Works on sale now; include_sold adds sold works. Attributes are the seller’s; null means unspecified, never estimated. completeness says whether every work was checked. A wall — wall: {width, height, furniture_width, furniture_height, unit} — keeps only works whose size suits it by Fold’s rules of thumb, and wall_fit gives the size range and the reasoning to relay: a rule of thumb, not a measurement of the room. With a wall, query may be left out. similar_to {artwork_id | image_url | image_base64} keeps only works that look like it, at or above Fold’s similarity threshold, the closest first, each with its similarity from 0 to 1: how alike the photographs look to an image model, not a judgement of style or quality. With similar_to, query may be left out. A photo is used for this search only and kept nowhere. Each of the first 5 matches carries offer — the impression to buy (listing_id), whether it can be bought now, its price, delivery, ship-by and arrival dates and returns — and, with the buyer’s US ZIP code in ships_to, the first 3 a delivered_estimate with sales tax. Pass offer.listing_id straight to the checkout, which checks availability itself. Every answer ends with next_actions: the next call, its ids filled in. The first 3 works shown come with a small picture of each, attached after the answer as images, so you can see how they look — colour, mood, whether one suits a room or a photo — rather than going by words alone; image.url is the full size.
| Name | Required | Description | Default |
|---|---|---|---|
| wall | No | The wall the work will hang on: only works whose size suits it. | |
| limit | No | Maximum matches. Default 10, hard cap 100. | |
| query | No | What the buyer is looking for, in their words. Leave it out only to search by a wall or similar_to alone. | |
| style | No | Any of these styles. | |
| colors | No | Every one of these among the colours the seller confirmed for the work. | |
| framed | No | Framed (true) or unframed (false), as the seller stated. | |
| medium | No | Any of these media; a family such as painting or print includes its members. | |
| signed | No | Signed by the artist, as the seller stated. | |
| edition | No | unique: one of a kind; edition: one impression of an edition. | |
| subject | No | Any of these subjects. | |
| ships_to | No | Where the buyer wants it delivered. Fold delivers to the 50 US states and DC. | |
| similar_to | No | A work, or a photo, the works must look like. | |
| orientation | No | Any of: portrait (taller than wide), landscape (wider than tall), square. | |
| include_sold | No | Also include works that have already sold. Off by default. Works taken off sale are never returned either way. | |
| max_width_in | No | Width at most this, in inches. | |
| min_width_in | No | Width at least this, in inches. | |
| max_height_in | No | Height at most this, in inches. | |
| max_price_usd | No | Highest acceptable price, in US dollars. | |
| min_height_in | No | Height at least this, in inches. | |
| min_price_usd | No | Lowest acceptable price, in US dollars. | |
| ready_to_hang | No | Ready to hang, as the seller stated. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only/idempotent/non-destructive, and the description layers rich behavior on top: near_matches semantics, null-means-unknown, filter-wins-over-words precedence, applied_filters/understood/fold_derived reporting, completeness, next_actions, and offer/listing_id passthrough to checkout. It stops just short of describing result ordering or pagination beyond similarity ordering, so a 4 rather than 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?
It is front-loaded with the when-to-use clause, but the body is a dense, run-on wall of text that mixes result-shape, filter precedence, wall logic, similarity, offers and images into long sentences. For 21 parameters the length is defensible, yet it could be structured with clearer separation to be scannable.
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?
Despite no output schema, the description thoroughly covers return shape (matches vs near_matches, applied_filters, understood, next_actions, offer, images) and caveats (seller-stated attributes, unknown never a no, verification boundary). An agent has enough to interpret and act on results correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (baseline 3), but the description adds genuine semantics beyond the schema: query accepts free words and multiple languages, filters override words, corrected spellings surface in understood, ships_to with state/ZIP unlocks delivered_estimate and tax, and similar_to's threshold is Fold's similarity model, not style judgement. This substantially exceeds what the schema documents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb and resource ('find original paintings, prints, photographs or sculpture from independent artists') and enumerates the facets (subject, style, colour, size, budget, wall, visual similarity). An agent can distinguish this from get_artwork or check_availability 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 frames when to use ('Use this when someone wants to find...') and states the alternative paths and their preconditions ('With a wall, query may be left out', 'With similar_to, query may be left out'). It also clarifies what is not filterable (authenticity/provenance) and routes to _verification, which prevents wrong selections.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the buyer has chosen one work and wants to buy it. It answers with checkout_url, a page on Fold’s own site for that one work, where the buyer enters the delivery address, sees the total with sales tax and the terms, and pays. It charges nothing and reserves nothing: the work can still sell to someone else until the buyer presses Pay, and the link works once and lapses at expires_at. Give the link to the buyer or open it in your browser. It checks availability itself, so call it straight from a search’s offer.listing_id or get_artwork’s listings, with no other call first; one listing_id per call, since each work is its own purchase. The buyer needs no account and never signs in: on the page they give a name, an e-mail for the order confirmation and a US delivery address, and pay. If the work has sold, or another buyer is paying for it, the refusal carries out_of_stock: what the work is now, and up to three similar works on sale here to offer the buyer instead.
| Name | Required | Description | Default |
|---|---|---|---|
| listing_id | Yes | A single listing_id from get_artwork or check_availability. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: no charge, no reservation, the work can still sell to another buyer, the link works once and lapses at expires_at, and the buyer needs no account. These details reconcile cleanly with readOnlyHint=false (a link is created) and idempotentHint=false (single-use, expiring link). The out_of_stock refusal shape is disclosed, which annotations could never 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 the trigger and the returned artifact, then layers constraints and the failure branch in a sensible order. It is dense rather than padded, though the buyer-page narrative (name, e-mail, US delivery address) is slightly more than an agent needs to invoke the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description carries the full burden — and it names checkout_url, expires_at, and the out_of_stock refusal contents. For a single-parameter tool with clear annotations, nothing an agent needs to call or interpret the result 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 baseline is 3; the description still adds real meaning by specifying where listing_id comes from (search offer.listing_id, get_artwork listings) and that exactly one is accepted per call. It adds the cardinality constraint the schema cannot express (maxLength aside).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Get a checkout link' for one chosen work) and immediately names the return value (checkout_url) and what it is (a page on Fold's own site for that one work). It also distinguishes itself from adjacent steps by saying it checks availability itself, so no prior call is needed — an agent can place it precisely in the buy flow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit trigger ('when the buyer has chosen one work and wants to buy it'), explicit no-prerequisite guidance ('call it straight from a search's offer.listing_id or get_artwork's listings, with no other call first'), and an explicit cardinality rule ('one listing_id per call, since each work is its own purchase'). It even covers the failure branch, telling the agent to offer up to three similar works from the out_of_stock refusal.
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.
search_artworks1 field changedInput schema / properties / similar_to / properties / min_similarityAdded value: +{
+ "description": "The least similarity a work must reach, 0.50 to 1; Fold's threshold, 0.60, when left out. Lower it only when the buyer would see works less alike.",
+ "maximum": 1,
+ "minimum": 0.5,
+ "type": "number"
+}cancel_purchaseconfirm_purchasefind_artworks_for_wallfind_similar_artworksget_purchasesave_search_alert1 field changedInput schema / properties / wall / descriptionPrevious value: -"Only works whose size suits this wall, as find_artworks_for_wall reads it."New value: +"Only works whose size suits this wall, as search_artworks’ wall reads it."search_artworks2 fields changedInput schema / properties / query / descriptionPrevious value: -"What the buyer is looking for, in their words."New value: +"What the buyer is looking for, in their words. Leave it out only to search by a wall or similar_to alone."Input schema / requiredRemoved value: -[
- "query"
-]set_deliverystart_checkoutstart_purchasecancel_search_alertfind_similar_artworksget_search_alertsave_search_alertsearch_artworks1 field changedInput schema / properties / similar_toAdded value: +{
+ "additionalProperties": false,
+ "description": "A work, or a photo, the works must look like.",
+ "properties": {
+ "artwork_id": {
+ "description": "A work on Fold to find works like: an artwork_id from search_artworks.",
+ "maxLength": 128,
+ "minLength": 1,
+ "type": "string"
+ },
+ "image_base64": {
+ "description": "A photo to find works like, inline: a JPEG, PNG or WebP as base64 or a data: URL, at most 700 KB. Used for this search only, and kept nowhere.",
+ "maxLength": 1000000,
+ "minLength": 1,
+ "type": "string"
+ },
+ "image_url": {
+ "description": "A photo to find works like: its https address. Fetched once, used for this search only, and kept nowhere.",
+ "maxLength": 2048,
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "type": "object"
+}find_artworks_for_wallsearch_artworks1 field changedInput schema / properties / wallAdded value: +{
+ "additionalProperties": false,
+ "description": "The wall the work will hang on: only works whose size suits it.",
+ "properties": {
+ "furniture_height": {
+ "description": "The furniture’s height from the floor, to hang the work above it. Give it with furniture_width.",
+ "exclusiveMinimum": 0,
+ "type": "number"
+ },
+ "furniture_width": {
+ "description": "The width of the furniture the work will hang above — a sofa, a bed, a sideboard — if any.",
+ "exclusiveMinimum": 0,
+ "type": "number"
+ },
+ "height": {
+ "description": "The wall’s height from the floor, in `unit`.",
+ "exclusiveMinimum": 0,
+ "type": "number"
+ },
+ "unit": {
+ "description": "in (inches, the default) or cm.",
+ "enum": [
+ "in",
+ "cm"
+ ],
+ "type": "string"
+ },
+ "width": {
+ "description": "The wall’s width, in `unit`.",
+ "exclusiveMinimum": 0,
+ "type": "number"
+ }
+ },
+ "required": [
+ "width",
+ "height"
+ ],
+ "type": "object"
+}open_claimsearch_artworks1 field changedInput schema / properties / seller_stated_tags_onlyRemoved value: -{
- "description": "Kept for compatibility. Terms are only ever matched against the seller’s own words and tags, never a model’s, so this changes nothing.",
- "type": "boolean"
-}get_delivered_quoteget_order_statussearch_artworks19 fields changedInput schema / properties / colorsAdded value: +{
+ "description": "Every one of these among the colours the seller confirmed for the work.",
+ "items": {
+ "enum": [
+ "red",
+ "orange",
+ "yellow",
+ "green",
+ "teal",
+ "blue",
+ "purple",
+ "pink",
+ "brown",
+ "beige",
+ "black",
+ "grey",
+ "white"
+ ],
+ "type": "string"
+ },
+ "maxItems": 4,
+ "minItems": 1,
+ "type": "array"
+}Input schema / properties / editionAdded value: +{
+ "description": "unique: one of a kind; edition: one impression of an edition.",
+ "enum": [
+ "unique",
+ "edition"
+ ],
+ "type": "string"
+}Input schema / properties / framedAdded value: +{
+ "description": "Framed (true) or unframed (false), as the seller stated.",
+ "type": "boolean"
+}Input schema / properties / limit / descriptionPrevious value: -"Maximum results. Default 10, hard cap 100."New value: +"Maximum matches. Default 10, hard cap 100."Input schema / properties / max_height_inAdded value: +{
+ "description": "Height at most this, in inches.",
+ "exclusiveMinimum": 0,
+ "type": "number"
+}Input schema / properties / max_price_usd / descriptionPrevious value: -"Highest acceptable price."New value: +"Highest acceptable price, in US dollars."Input schema / properties / max_width_inAdded value: +{
+ "description": "Width at most this, in inches.",
+ "exclusiveMinimum": 0,
+ "type": "number"
+}Input schema / properties / mediumAdded value: +{
+ "description": "Any of these media; a family such as painting or print includes its members.",
+ "items": {
+ "enum": [
+ "painting",
+ "oil",
+ "acrylic",
+ "watercolor",
+ "gouache",
+ "tempera",
+ "drawing",
+ "charcoal",
+ "graphite",
+ "pastel",
+ "ink",
+ "print",
+ "screenprint",
+ "etching",
+ "lithograph",
+ "woodcut",
+ "linocut",
+ "giclee",
+ "monotype",
+ "photograph",
+ "sculpture",
+ "bronze",
+ "ceramic",
+ "glass",
+ "textile",
+ "collage",
+ "mixed_media",
+ "digital"
+ ],
+ "type": "string"
+ },
+ "maxItems": 12,
+ "minItems": 1,
+ "type": "array"
+}Input schema / properties / min_height_inAdded value: +{
+ "description": "Height at least this, in inches.",
+ "exclusiveMinimum": 0,
+ "type": "number"
+}Input schema / properties / min_price_usd / descriptionPrevious value: -"Lowest acceptable price."New value: +"Lowest acceptable price, in US dollars."Input schema / properties / min_width_inAdded value: +{
+ "description": "Width at least this, in inches.",
+ "exclusiveMinimum": 0,
+ "type": "number"
+}Input schema / properties / orientationAdded value: +{
+ "description": "Any of: portrait (taller than wide), landscape (wider than tall), square.",
+ "items": {
+ "enum": [
+ "portrait",
+ "landscape",
+ "square"
+ ],
+ "type": "string"
+ },
+ "maxItems": 3,
+ "minItems": 1,
+ "type": "array"
+}Input schema / properties / query / descriptionPrevious value: -"What the buyer is looking for, in natural language."New value: +"What the buyer is looking for, in their words."Input schema / properties / ready_to_hangAdded value: +{
+ "description": "Ready to hang, as the seller stated.",
+ "type": "boolean"
+}Input schema / properties / seller_stated_tags_only / descriptionPrevious value: -"When true, match only tags the seller asserted, excluding model-generated ones. Use when the buyer needs the seller to have made the claim themselves."New value: +"Kept for compatibility. Terms are only ever matched against the seller’s own words and tags, never a model’s, so this changes nothing."Input schema / properties / ships_toAdded value: +{
+ "additionalProperties": false,
+ "description": "Where the buyer wants it delivered. Fold delivers to the 50 US states and DC.",
+ "properties": {
+ "country": {
+ "description": "ISO 3166-1 alpha-2, e.g. US.",
+ "maxLength": 56,
+ "minLength": 2,
+ "type": "string"
+ },
+ "postal_code": {
+ "maxLength": 16,
+ "type": "string"
+ },
+ "region": {
+ "description": "The state, e.g. CO or Colorado.",
+ "maxLength": 56,
+ "type": "string"
+ }
+ },
+ "required": [
+ "country"
+ ],
+ "type": "object"
+}Input schema / properties / signedAdded value: +{
+ "description": "Signed by the artist, as the seller stated.",
+ "type": "boolean"
+}Input schema / properties / styleAdded value: +{
+ "description": "Any of these styles.",
+ "items": {
+ "enum": [
+ "abstract_expressionism",
+ "expressionism",
+ "impressionism",
+ "realism",
+ "photorealism",
+ "minimalism",
+ "geometric",
+ "pop_art",
+ "surrealism",
+ "folk",
+ "street_art",
+ "illustrative"
+ ],
+ "type": "string"
+ },
+ "maxItems": 12,
+ "minItems": 1,
+ "type": "array"
+}Input schema / properties / subjectAdded value: +{
+ "description": "Any of these subjects.",
+ "items": {
+ "enum": [
+ "abstract",
+ "landscape",
+ "seascape",
+ "cityscape",
+ "still_life",
+ "botanical",
+ "animals",
+ "portrait",
+ "figurative",
+ "interior",
+ "spiritual",
+ "text"
+ ],
+ "type": "string"
+ },
+ "maxItems": 12,
+ "minItems": 1,
+ "type": "array"
+}Original art and prints from independent artists, fair prices, and help for artists to sell.
Artwork provenance and works for sale: Origin Passports, Ethereum proofs, listings with proof
Find artist-credited art prints and canvas, made to order by Image Kind’s studio.
Search and shop curated second-hand design: furniture, lighting, art and designer bags.
Add one secure layer between your agents and this server.