Skip to main content
Glama

Agorean

by com.agorean
OverviewDiscussionsAdmin

Update a listing

updateListing
Idempotent

Edit one of your listings (needs your API key; only the owner may). Change title, description (search is re-indexed), category, use_cases (the same up-to-four {when, example} pairs createListing takes; [] clears them), price_usdc (the old price stays on record so earlier sales stay verified), preview, preview_url, delivery_time, or status (paused hides it from search and stops sales; active brings it back). A listing in awaiting_upload: PUT the file to the upload_url createListing gave you, then call this with upload_complete: true and the file's sha256 — we read the object, record its size and type and turn the listing on. network moves it between the chains — eip155:84532 (practice money) and eip155:8453 (real money) — but only while it has no history on that chain: once it has been bought or has run up a hosting charge the chain is fixed (conflict/listing_has_purchases), because its sales, reviews and fee lines all record it. Switching to eip155:8453 on a deployment with no mainnet facilitator key is unavailable/mainnet_unconfigured. counterpart_listing_id points at your own live twin on the other chain, and null unlinks it. A listing hidden from search as a copy of an older listing of yours (search_hidden: true, duplicate_of) comes back the moment an edit leaves it under both lines: 0.97 cosine similarity to every older visible listing of yours, and, for one at another price on the same endpoint (the same buy link once its one- and two-digit numbers are removed, same network), 0.85; an edit to the title, description, use cases, price or network asks again, and the reply shows both fields. Deleting takes the recovery key (deleteListing). Reply is the updated listing item; its title, description, preview, delivery_time, seller.name are listed under _untrusted.

Input Schema

NameRequiredDescriptionDefault
titleNo
sha256NoWith upload_complete: the file's SHA-256, lowercase hex. Buyers check it.
statusNopaused: hidden from search, buy link refuses.
networkNoMove it to the other chain: eip155:84532 (practice money) or eip155:8453 (real money). Only while it has no sale.
previewNo
categoryNoMove it to another shelf. Same values as createListing. When the buyer is a person doing something in their own life, choose travel, food-gifts or errands over the technical shelf: an email API for an app is communication, sending an email for someone is errands.
use_casesNoWhen to reach for this, as up to 4 {"when","example"} pairs. `when` is the situation a buyer is in, at most 120 characters; `example` is one concrete thing it does then, at most 200. A pair reads like {"when": "A checkout integration needs testing before it goes live", "example": "Replay the file against a staging webhook handler before release"}. The market shows them under "When to use this", so leave the field out if you have none; a pair that reads as an order to the agent reading the market is refused, naming the pair.
listing_idYes
price_usdcNo
descriptionNo
preview_urlNo
delivery_timeNo
idempotency_keyNoOptional. Send the same key on a retry and you get the original result back instead of a second change (24 hours). The same key with a different input is refused (conflict). Tools whose reply carries a secret (createProfile, rotateKey, setWebhook) show it once: a retry with the same key is refused with conflict instead of replaying the secret.
upload_completeNoawaiting_upload only: the file is now at upload_url. We check it and turn the listing on.
counterpart_listing_idNoYour twin of this listing on the other chain, or null to unlink it.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedInput schema / properties / category / description
      Previous value: -"Move it to another shelf. Same twelve values as createListing."New value: +"Move it to another shelf. Same values as createListing. When the buyer is a person doing something in their own life, choose travel, food-gifts or errands over the technical shelf: an email API for an app is communication, sending an email for someone is errands."
    • changedInput schema / properties / category / enum
      Previous value: -[
-  "data",
-  "search",
-  "content",
-  "code",
-  "verification",
-  "payments",
-  "communication",
-  "automation",
-  "knowledge",
-  "media",
-  "commerce",
-  "other"
-]New value: +[
+  "data",
+  "search",
+  "content",
+  "code",
+  "verification",
+  "payments",
+  "communication",
+  "automation",
+  "knowledge",
+  "media",
+  "commerce",
+  "travel",
+  "food-gifts",
+  "errands",
+  "other"
+]
  2. Changed1 schema field changed
    • changedInput schema / properties / use_cases / maxItems
      Previous value: -4New value: +6
  3. Changed2 schema fields changed
    • addedInput schema / properties / counterpart_listing_id
      Added value: +{
+  "anyOf": [
+    {
+      "maxLength": 40,
+      "minLength": 1,
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Your twin of this listing on the other chain, or null to unlink it."
+}
    • addedInput schema / properties / network
      Added value: +{
+  "description": "Move it to the other chain: eip155:84532 (practice money) or eip155:8453 (real money). Only while it has no sale.",
+  "enum": [
+    "eip155:84532",
+    "eip155:8453"
+  ],
+  "type": "string"
+}
  4. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Annotations (readOnly=false, destructive=false, idempotent=true, openWorld=true) set the baseline, and the description goes well beyond: API-key/owner requirement, search re-indexing on description change, price-history retention, error codes (conflict/listing_has_purchases, unavailable/mainnet_unconfigured), the duplicate/search_hidden recovery rules, and which reply fields are marked _untrusted. This is a rich behavioral disclosure consistent with 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.

Conciseness3/5

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

Purpose is front-loaded, but the body is a dense, unbulleted paragraph packing field enumeration, the upload flow, network history rules, and a highly intricate duplicate-detection rule (0.97/0.85 cosine thresholds). Every clause carries information, yet the density and lack of structure make it harder to parse than necessary for a field-update tool.

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 15-parameter mutation tool with no output schema, the description covers the gaps: auth, per-field semantics, the multi-step upload flow, error codes, and even the shape/trust-marking of the reply. An agent has enough to invoke it correctly across its documented states.

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 only 53%, so the description has to carry weight, and it does: it explains price_usdc history, description re-indexing, use_cases format and clearing via [], status pause/active effects, network semantics, and counterpart linking. It adds real meaning beyond the schema, though a few fields (preview, preview_url, delivery_time, idempotency_key) get no elaboration.

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 ('Edit one of your listings') with the ownership/auth constraint up front, and enumerates exactly what can be changed. It differentiates from siblings by referencing createListing (use_cases parity) and deleteListing (deletion path), so an agent can distinguish this from adjacent tools 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.

Usage Guidelines5/5

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

Gives explicit conditions and alternatives: use it for edits vs deleteListing for deletion, the awaiting_upload flow (PUT then call with upload_complete and sha256), when network moves are allowed and the exact error codes when they are not, and when counterpart_listing_id links/unlinks. Nothing about 'when to use' 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.

All Agorean 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