Skip to main content
Glama

Fold Laboratories

by com.foldlaboratories
OverviewDiscussionsAdmin

Save a search and alert on new works

save_search_alert

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.

Input Schema

NameRequiredDescriptionDefault
wallNoOnly works whose size suits this wall, as search_artworks’ wall reads it.
emailNoThe 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.
queryNoWhat the buyer is looking for, in their words, as for search_artworks.
styleNoAny of these styles.
colorsNoEvery one of these among the colours the seller confirmed for the work.
framedNoFramed (true) or unframed (false), as the seller stated.
mediumNoAny of these media; a family such as painting or print includes its members.
signedNoSigned by the artist, as the seller stated.
editionNounique: one of a kind; edition: one impression of an edition.
subjectNoAny of these subjects.
ships_toNoWhere the buyer wants it delivered. Fold delivers to the 50 US states and DC.
orientationNoAny of: portrait (taller than wide), landscape (wider than tall), square.
webhook_urlNoYour https endpoint for search_alert.new_works events, signed as Standard Webhooks specifies. It must echo the verification event’s data.challenge.
max_width_inNoWidth at most this, in inches.
min_width_inNoWidth at least this, in inches.
max_height_inNoHeight at most this, in inches.
max_price_usdNoHighest acceptable price, in US dollars.
min_height_inNoHeight at least this, in inches.
min_price_usdNoLowest acceptable price, in US dollars.
ready_to_hangNoReady to hang, as the seller stated.
include_matureNoAlso announce works their sellers flagged as mature content. Only when the buyer asked.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / wall / description
      Previous 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."
  2. Added

TDQS

A4.8/5.0
Behavior5/5

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.

Conciseness4/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines5/5

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.

All Fold Laboratories toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources