Skip to main content
Glama

Buy an item

buy
Destructive

Buy an item: any starter credit pays first for a new utility or kit it covers in full, else your balance. Utilities start at once; kits return a single-use download link. Pass instance_id to renew a utility you own. Above what is left of today's spending limit, the order waits (status pending_approval, nothing taken) and your owner gets one email to approve it within 24 hours; get_order shows the outcome. Retry with the same idempotency_key: never a second order. Human services (shelf human, done by our own team): quote_human_service first (free), then pass brief (get_item: details.brief_schema), max_price_cents, and any login only as secret; then get_job with delivery.job_id. A website test first waits for your proof that each site is yours (verify_job_sites). More: /llms/human-services.md. A kit your owner bought is a free update in every later version with the same main version number (1.0.2 to 1.2.0: no balance, limit or approval); a new main version (2.0.0) is a new purchase.

Example tool call

This call uses example arguments supplied in the tool’s input schema.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "item": "memory-locker",
      "idempotency_key": "example-key-1",
      "max_price_cents": 100
    },
    "name": "buy"
  }
}

Input Schema

NameRequiredDescriptionDefault
itemYesItem slug from search_catalog or get_item; a first site check badge: buy_site_badge
briefNoHuman services only: what our team needs, in the service's schema (get_item shows details.brief_schema).
secretNoHuman services only: a test login or access key. Write-only: encrypted, shown only to the one team member doing the job, deleted when it closes. Never put it in brief.
instance_idNoTo renew: the instance_id (list_utilities) of a utility you own. Leave out for a new one.
passport_tokenNoYour amp_ token, only if you have no app sign-in and cannot send a header.
idempotency_keyNoYour own key, no spaces: reuse it to retry safely without paying twice
max_price_centsNoThe most this order may cost, in US cents: a higher price (as we count it) is refused and nothing is taken.
inbox_instance_idNoOne of your owner's webhook inboxes (its instance_id from list_utilities): what happens to this order (approved, declined, expired) and its job is written there.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changed
    • changedInput schema / properties / idempotency_key / description
      Previous value: -"Reuse to retry safely without paying twice"New value: +"Your own key, no spaces: reuse it to retry safely without paying twice"
    • changedInput schema / properties / inbox_instance_id / description
      Previous value: -"One of your owner's webhook inboxes: what happens to this order (approved, declined, expired) and its job is written there."New value: +"One of your owner's webhook inboxes (its instance_id from list_utilities): what happens to this order (approved, declined, expired) and its job is written there."
    • changedInput schema / properties / instance_id / description
      Previous value: -"To renew: the utility instance id you own. Leave out for a new one."New value: +"To renew: the instance_id (list_utilities) of a utility you own. Leave out for a new one."
    • changedInput schema / properties / item / description
      Previous value: -"Item slug from search_catalog"New value: +"Item slug from search_catalog or get_item; a first site check badge: buy_site_badge"
  2. Changed2 schema fields changed
    • addedInput schema / examples
      Added value: +[
      +  {
      +    "idempotency_key": "example-key-1",
      +    "item": "memory-locker",
      +    "max_price_cents": 100
      +  }
      +]
    • changedInput schema / properties / passport_token / description
      Previous value: -"Your amp_ token, only if your app has no sign-in and cannot send it as an Authorization header."New value: +"Your amp_ token, only if you have no app sign-in and cannot send a header."
  3. Changed4 schema fields changed
    • removedInput schema / $schema
      Removed value: -"https://json-schema.org/draft/2020-12/schema"
    • changedInput schema / properties / passport_token / description
      Previous value: -"Your amp_ token, only if your client cannot send it as an Authorization header; leave it out when your MCP app signed in."New value: +"Your amp_ token, only if your app has no sign-in and cannot send it as an Authorization header."
    • addedInput schema / properties / passport_token / maxLength
      Added value: +200
    • removedInput schema / properties / passport_token / pattern
      Removed value: -"^amp_(?:s_)?[A-Za-z0-9_-]{43}$"
  4. Changed4 schema fields changed
    • addedInput schema / properties / brief
      Added value: +{
      +  "additionalProperties": {},
      +  "description": "Human services only: what our team needs, in the service's schema (get_item shows details.brief_schema).",
      +  "propertyNames": {
      +    "type": "string"
      +  },
      +  "type": "object"
      +}
    • addedInput schema / properties / inbox_instance_id
      Added value: +{
      +  "description": "One of your owner's webhook inboxes: what happens to this order (approved, declined, expired) and its job is written there.",
      +  "maxLength": 64,
      +  "minLength": 1,
      +  "type": "string"
      +}
    • addedInput schema / properties / max_price_cents
      Added value: +{
      +  "description": "The most this order may cost, in US cents: a higher price (as we count it) is refused and nothing is taken.",
      +  "maximum": 10000000,
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • addedInput schema / properties / secret
      Added value: +{
      +  "description": "Human services only: a test login or access key. Write-only: encrypted, shown only to the one team member doing the job, deleted when it closes. Never put it in brief.",
      +  "maxLength": 2000,
      +  "minLength": 1,
      +  "type": "string"
      +}
  5. Changed3 schema fields changed
    • addedInput schema / additionalProperties
      Added value: +false
    • addedInput schema / properties / instance_id / description
      Added value: +"To renew: the utility instance id you own. Leave out for a new one."
    • changedInput schema / properties / passport_token / description
      Previous value: -"Leave it out when your MCP app signed in to AgentMart (it is refused then). Otherwise your passport bearer token (amp_...) or session token (amp_s_...), only if your client cannot send it as an Authorization header. A token here sits in your context, so it never authorizes sensitive actions."New value: +"Your amp_ token, only if your client cannot send it as an Authorization header; leave it out when your MCP app signed in."
  6. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Goes far beyond the annotations: it discloses that orders above the daily limit produce status pending_approval with nothing charged, a 24-hour owner email, that secrets are write-only and deleted when the job closes, and that kits with the same main version are free updates. This is consistent with destructiveHint=true and idempotentHint=false, since safety comes from the caller-supplied idempotency key rather than inherent idempotency.

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?

The first clause is well front-loaded, but the remainder is a long run-on chain of semicolon-joined clauses covering pricing, approval, human services, site verification, docs links, and version upgrades. Every fact is individually useful, yet the density makes it hard to scan and the closing version-upgrade paragraph buries a fairly important purchase rule.

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

Completeness4/5

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

Given eight parameters, a nested object, no output schema, and a destructive write, the description covers the critical decision paths: payment order, approval/orphaned order state, human-service preconditions, renewal, and idempotent retry. Only inbox_instance_id and passport_token are left entirely to the schema.

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 already 100%, so the schema baseline is a 3, but the description adds real meaning: idempotency_key governs retry safety, brief requires the service's brief_schema plus max_price_cents and secret (never inside brief), and instance_id selects renewal over a new purchase. It does not explain inbox_instance_id or passport_token, so it is not fully comprehensive.

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?

Opens with a specific verb and resource ('Buy an item') and immediately defines payment semantics (starter credit first, then balance) and the two item classes (utilities vs. kits). It clearly distinguishes itself from siblings by routing human services to quote_human_service and outcomes to get_order.

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?

Explicit when-to-use and when-to-do-something-else guidance: pass instance_id to renew rather than buy new, call quote_human_service first for human services, run verify_job_sites before a website test, and reuse the same idempotency_key to retry safely. Over-limit behavior and the approval path are also spelled out.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.