Skip to main content
Glama

Configure merchant tokens (replaces)

insumer_configure_tokens
DestructiveIdempotent

Configure merchant token discount tiers by replacing token settings with own and partner tokens, max 8 total, owner only. Discounts are whole numbers 1-50.

Instructions

Configure merchant token discount tiers. Set own token and/or partner tokens. Replaces the existing token configuration. Max 8 tokens total. Tier discounts are whole numbers from 1 to 50; a value with decimals is refused. Owner only.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
idYesMerchant ID
ownTokenNoMerchant's own token configuration, or null to remove
partnerTokensNoPartner token configurations

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
okNotrue when the API call succeeded
dataNoThe endpoint's payload: a signed attestation, trust profile, discount, merchant or token records
keysNoJWKS entries (insumer_jwks)
metaNoResponse metadata such as version and timestamp
errorNoError details when ok is false
itemsNoThe result when the endpoint returns a JSON array
messageNoA plain-text result (insumer_setup), or a message from the API

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changedv1.17.1
    • changedInput schema / properties / ownToken / anyOf
      Previous value: -[
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "chainId": {
      -        "anyOf": [
      -          {
      -            "enum": [
      -              "1",
      -              "50",
      -              "56",
      -              "8453",
      -              "43114",
      -              "137",
      -              "42161",
      -              "10",
      -              "88888",
      -              "1868",
      -              "98866",
      -              "480",
      -              "146",
      -              "100",
      -              "5000",
      -              "534352",
      -              "59144",
      -              "324",
      -              "81457",
      -              "42220",
      -              "204",
      -              "130",
      -              "57073",
      -              "1329",
      -              "80094",
      -              "33139",
      -              "4663",
      -              "167000",
      -              "2020",
      -              "88",
      -              "5042"
      -            ],
      -            "type": "string"
      -          },
      -          {
      -            "type": "integer"
      -          },
      -          {
      -            "const": "solana",
      -            "type": "string"
      -          },
      -          {
      -            "const": "xrpl",
      -            "type": "string"
      -          }
      -        ],
      -        "description": "Merchant onboarding chain: one of the EVM chain IDs listed in this schema, 'solana', or 'xrpl'. Merchant token and NFT configs are not available on Bitcoin, Tron, Stellar or Sui."
      -      },
      -      "contractAddress": {
      -        "description": "Token contract address. For XRPL: use r-address issuer for trust line tokens, or 'native' for XRP.",
      -        "maxLength": 200,
      -        "minLength": 1,
      -        "pattern": "^[A-Za-z0-9:_]+$",
      -        "type": "string"
      -      },
      -      "currency": {
      -        "description": "XRPL trust line currency code (e.g. 'RLUSD', 'USDC', or 'USD'). Required for XRPL trust line tokens. Standard codes ≤ 3 chars; longer names like 'RLUSD' are auto hex-encoded by the API.",
      -        "maxLength": 40,
      -        "pattern": "^[A-Za-z0-9]+$",
      -        "type": "string"
      -      },
      -      "decimals": {
      -        "description": "Token decimals (0-18). Required: the merchant registry stores it with each token and rejects a config without it. 6 for USDC, 18 for most ERC-20s.",
      -        "maximum": 18,
      -        "minimum": 0,
      -        "type": "integer"
      -      },
      -      "symbol": {
      -        "description": "Token symbol, e.g. 'UNI'",
      -        "maxLength": 10,
      -        "type": "string"
      -      },
      -      "tiers": {
      -        "description": "1-4 discount tiers",
      -        "items": {
      -          "additionalProperties": false,
      -          "properties": {
      -            "discount": {
      -              "description": "Discount percentage (1-50)",
      -              "maximum": 50,
      -              "minimum": 1,
      -              "type": "integer"
      -            },
      -            "name": {
      -              "description": "Tier name, e.g. 'Gold', 'Silver'",
      -              "maxLength": 30,
      -              "type": "string"
      -            },
      -            "threshold": {
      -              "description": "Minimum token balance for this tier",
      -              "exclusiveMinimum": 0,
      -              "type": "number"
      -            }
      -          },
      -          "required": [
      -            "name",
      -            "threshold",
      -            "discount"
      -          ],
      -          "type": "object"
      -        },
      -        "maxItems": 4,
      -        "minItems": 1,
      -        "type": "array"
      -      }
      -    },
      -    "required": [
      -      "symbol",
      -      "chainId",
      -      "contractAddress",
      -      "decimals",
      -      "tiers"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "alsoOn": {
      +        "description": "Optional: the same token on other networks, up to 9 (EVM chains and Solana; not the XRP Ledger, not a native coin). The store decides which deployments count as the same token. Each network's balance is read in that token's own decimals there, the balances are added exactly, and the tier is awarded once. A read that fails on any listed network refuses the whole check (rpc_failure), never a partial total. When re-saving, carry each token's alsoOn through, or its other networks are removed.",
      +        "items": {
      +          "additionalProperties": false,
      +          "properties": {
      +            "chainId": {
      +              "anyOf": [
      +                {
      +                  "exclusiveMinimum": 0,
      +                  "type": "integer"
      +                },
      +                {
      +                  "const": "solana",
      +                  "type": "string"
      +                }
      +              ],
      +              "description": "EVM chain ID, or 'solana'"
      +            },
      +            "contractAddress": {
      +              "description": "The same token's contract (EVM) or mint (Solana) on that network; not 'native'",
      +              "maxLength": 64,
      +              "minLength": 1,
      +              "type": "string"
      +            }
      +          },
      +          "required": [
      +            "chainId",
      +            "contractAddress"
      +          ],
      +          "type": "object"
      +        },
      +        "maxItems": 9,
      +        "type": "array"
      +      },
      +      "chainId": {
      +        "anyOf": [
      +          {
      +            "enum": [
      +              "1",
      +              "50",
      +              "56",
      +              "8453",
      +              "43114",
      +              "137",
      +              "42161",
      +              "10",
      +              "88888",
      +              "1868",
      +              "98866",
      +              "480",
      +              "146",
      +              "100",
      +              "5000",
      +              "534352",
      +              "59144",
      +              "324",
      +              "81457",
      +              "42220",
      +              "204",
      +              "130",
      +              "57073",
      +              "1329",
      +              "80094",
      +              "33139",
      +              "4663",
      +              "167000",
      +              "2020",
      +              "88",
      +              "5042"
      +            ],
      +            "type": "string"
      +          },
      +          {
      +            "type": "integer"
      +          },
      +          {
      +            "const": "solana",
      +            "type": "string"
      +          },
      +          {
      +            "const": "xrpl",
      +            "type": "string"
      +          }
      +        ],
      +        "description": "Merchant onboarding chain: one of the EVM chain IDs listed in this schema, 'solana', or 'xrpl'. Merchant token and NFT configs are not available on Bitcoin, Tron, Stellar or Sui."
      +      },
      +      "contractAddress": {
      +        "description": "Token contract address. For XRPL: use r-address issuer for trust line tokens, or 'native' for XRP.",
      +        "maxLength": 200,
      +        "minLength": 1,
      +        "pattern": "^[A-Za-z0-9:_]+$",
      +        "type": "string"
      +      },
      +      "currency": {
      +        "description": "XRPL trust line currency code: a 3-character code (e.g. 'USD'), a token name of 1 to 20 printable ASCII characters (e.g. 'RLUSD'), or a 40-character hex code. Case-sensitive: send it exactly as the issuer created it. 'XRP' is the native coin and is not accepted here: use contractAddress 'native'. Required for XRPL trust line tokens.",
      +        "maxLength": 40,
      +        "minLength": 1,
      +        "pattern": "^[\\x20-\\x7E]+$",
      +        "type": "string"
      +      },
      +      "decimals": {
      +        "description": "Token decimals (0-18). Required: the merchant registry stores it with each token and rejects a config without it. 6 for USDC, 18 for most ERC-20s.",
      +        "maximum": 18,
      +        "minimum": 0,
      +        "type": "integer"
      +      },
      +      "enabled": {
      +        "description": "true or false, never a string. false switches the own token off; leave it out or send true to keep it on.",
      +        "type": "boolean"
      +      },
      +      "logo": {
      +        "description": "Logo URL for the token, shown in the public directory (max 500 characters). Optional.",
      +        "maxLength": 500,
      +        "type": "string"
      +      },
      +      "name": {
      +        "description": "Display name of the token, shown in the public directory (max 100 characters). Optional.",
      +        "maxLength": 100,
      +        "type": "string"
      +      },
      +      "symbol": {
      +        "description": "Token symbol, e.g. 'UNI'",
      +        "maxLength": 10,
      +        "type": "string"
      +      },
      +      "tiers": {
      +        "description": "1-4 discount tiers",
      +        "items": {
      +          "additionalProperties": false,
      +          "properties": {
      +            "discount": {
      +              "description": "Discount percentage: a whole number from 1 to 50, no decimals",
      +              "maximum": 50,
      +              "minimum": 1,
      +              "type": "integer"
      +            },
      +            "name": {
      +              "description": "Tier name, e.g. 'Gold', 'Silver'",
      +              "maxLength": 30,
      +              "type": "string"
      +            },
      +            "threshold": {
      +              "description": "Minimum token balance for this tier",
      +              "exclusiveMinimum": 0,
      +              "type": "number"
      +            }
      +          },
      +          "required": [
      +            "name",
      +            "threshold",
      +            "discount"
      +          ],
      +          "type": "object"
      +        },
      +        "maxItems": 4,
      +        "minItems": 1,
      +        "type": "array"
      +      }
      +    },
      +    "required": [
      +      "symbol",
      +      "chainId",
      +      "contractAddress",
      +      "decimals",
      +      "tiers"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • removedInput schema / properties / partnerTokens / items / $ref
      Removed value: -"#/properties/ownToken/anyOf/0"
    • addedInput schema / properties / partnerTokens / items / additionalProperties
      Added value: +false
    • addedInput schema / properties / partnerTokens / items / properties
      Added value: +{
      +  "alsoOn": {
      +    "$ref": "#/properties/ownToken/anyOf/0/properties/alsoOn"
      +  },
      +  "chainId": {
      +    "$ref": "#/properties/ownToken/anyOf/0/properties/chainId"
      +  },
      +  "contractAddress": {
      +    "$ref": "#/properties/ownToken/anyOf/0/properties/contractAddress"
      +  },
      +  "currency": {
      +    "$ref": "#/properties/ownToken/anyOf/0/properties/currency"
      +  },
      +  "decimals": {
      +    "$ref": "#/properties/ownToken/anyOf/0/properties/decimals"
      +  },
      +  "logo": {
      +    "$ref": "#/properties/ownToken/anyOf/0/properties/logo"
      +  },
      +  "name": {
      +    "$ref": "#/properties/ownToken/anyOf/0/properties/name"
      +  },
      +  "symbol": {
      +    "$ref": "#/properties/ownToken/anyOf/0/properties/symbol"
      +  },
      +  "tiers": {
      +    "$ref": "#/properties/ownToken/anyOf/0/properties/tiers"
      +  }
      +}
    • addedInput schema / properties / partnerTokens / items / required
      Added value: +[
      +  "symbol",
      +  "chainId",
      +  "contractAddress",
      +  "decimals",
      +  "tiers"
      +]
    • addedInput schema / properties / partnerTokens / items / type
      Added value: +"object"
  2. Changed6 schema fields changedv1.16.0
    • addedInput schema / properties / id / maxLength
      Added value: +100
    • addedInput schema / properties / id / minLength
      Added value: +1
    • addedInput schema / properties / id / pattern
      Added value: +"^[a-zA-Z0-9_-]+$"
    • changedInput schema / properties / ownToken / anyOf
      Previous value: -[
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "chainId": {
      -        "anyOf": [
      -          {
      -            "enum": [
      -              "1",
      -              "56",
      -              "8453",
      -              "43114",
      -              "137",
      -              "42161",
      -              "10",
      -              "88888",
      -              "1868",
      -              "98866",
      -              "480",
      -              "146",
      -              "100",
      -              "5000",
      -              "534352",
      -              "59144",
      -              "324",
      -              "81457",
      -              "42220",
      -              "1284",
      -              "204",
      -              "130",
      -              "57073",
      -              "1329",
      -              "80094",
      -              "33139",
      -              "167000",
      -              "2020",
      -              "1285",
      -              "88"
      -            ],
      -            "type": "string"
      -          },
      -          {
      -            "type": "integer"
      -          },
      -          {
      -            "const": "solana",
      -            "type": "string"
      -          },
      -          {
      -            "const": "xrpl",
      -            "type": "string"
      -          },
      -          {
      -            "const": "bitcoin",
      -            "type": "string"
      -          }
      -        ],
      -        "description": "Onboarding chain: any supported EVM chain ID (1, 56, 8453, 43114, 137, 42161, 10, 146, 100, 5000, 534352, 59144, 324, 81457, 42220, 1284, 204, 130, 57073, 1329, 80094, 33139, 88888, 1868, 98866, 480, 167000, 2020, 1285, 88), 'solana', 'xrpl', or 'bitcoin'"
      -      },
      -      "contractAddress": {
      -        "description": "Token contract address. For XRPL: use r-address issuer for trust line tokens, or 'native' for XRP.",
      -        "type": "string"
      -      },
      -      "currency": {
      -        "description": "XRPL trust line currency code (e.g. 'RLUSD', 'USDC', or 'USD'). Required for XRPL trust line tokens. Standard codes ≤ 3 chars; longer names like 'RLUSD' are auto hex-encoded by the API.",
      -        "type": "string"
      -      },
      -      "decimals": {
      -        "description": "Token decimals (0-18, default 18)",
      -        "maximum": 18,
      -        "minimum": 0,
      -        "type": "integer"
      -      },
      -      "symbol": {
      -        "description": "Token symbol, e.g. 'UNI'",
      -        "maxLength": 10,
      -        "type": "string"
      -      },
      -      "tiers": {
      -        "description": "1-4 discount tiers",
      -        "items": {
      -          "additionalProperties": false,
      -          "properties": {
      -            "discount": {
      -              "description": "Discount percentage (1-50)",
      -              "maximum": 50,
      -              "minimum": 1,
      -              "type": "integer"
      -            },
      -            "name": {
      -              "description": "Tier name, e.g. 'Gold', 'Silver'",
      -              "maxLength": 30,
      -              "type": "string"
      -            },
      -            "threshold": {
      -              "description": "Minimum token balance for this tier",
      -              "exclusiveMinimum": 0,
      -              "type": "number"
      -            }
      -          },
      -          "required": [
      -            "name",
      -            "threshold",
      -            "discount"
      -          ],
      -          "type": "object"
      -        },
      -        "maxItems": 4,
      -        "minItems": 1,
      -        "type": "array"
      -      }
      -    },
      -    "required": [
      -      "symbol",
      -      "chainId",
      -      "contractAddress",
      -      "tiers"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "chainId": {
      +        "anyOf": [
      +          {
      +            "enum": [
      +              "1",
      +              "50",
      +              "56",
      +              "8453",
      +              "43114",
      +              "137",
      +              "42161",
      +              "10",
      +              "88888",
      +              "1868",
      +              "98866",
      +              "480",
      +              "146",
      +              "100",
      +              "5000",
      +              "534352",
      +              "59144",
      +              "324",
      +              "81457",
      +              "42220",
      +              "204",
      +              "130",
      +              "57073",
      +              "1329",
      +              "80094",
      +              "33139",
      +              "4663",
      +              "167000",
      +              "2020",
      +              "88",
      +              "5042"
      +            ],
      +            "type": "string"
      +          },
      +          {
      +            "type": "integer"
      +          },
      +          {
      +            "const": "solana",
      +            "type": "string"
      +          },
      +          {
      +            "const": "xrpl",
      +            "type": "string"
      +          }
      +        ],
      +        "description": "Merchant onboarding chain: one of the EVM chain IDs listed in this schema, 'solana', or 'xrpl'. Merchant token and NFT configs are not available on Bitcoin, Tron, Stellar or Sui."
      +      },
      +      "contractAddress": {
      +        "description": "Token contract address. For XRPL: use r-address issuer for trust line tokens, or 'native' for XRP.",
      +        "maxLength": 200,
      +        "minLength": 1,
      +        "pattern": "^[A-Za-z0-9:_]+$",
      +        "type": "string"
      +      },
      +      "currency": {
      +        "description": "XRPL trust line currency code (e.g. 'RLUSD', 'USDC', or 'USD'). Required for XRPL trust line tokens. Standard codes ≤ 3 chars; longer names like 'RLUSD' are auto hex-encoded by the API.",
      +        "maxLength": 40,
      +        "pattern": "^[A-Za-z0-9]+$",
      +        "type": "string"
      +      },
      +      "decimals": {
      +        "description": "Token decimals (0-18). Required: the merchant registry stores it with each token and rejects a config without it. 6 for USDC, 18 for most ERC-20s.",
      +        "maximum": 18,
      +        "minimum": 0,
      +        "type": "integer"
      +      },
      +      "symbol": {
      +        "description": "Token symbol, e.g. 'UNI'",
      +        "maxLength": 10,
      +        "type": "string"
      +      },
      +      "tiers": {
      +        "description": "1-4 discount tiers",
      +        "items": {
      +          "additionalProperties": false,
      +          "properties": {
      +            "discount": {
      +              "description": "Discount percentage (1-50)",
      +              "maximum": 50,
      +              "minimum": 1,
      +              "type": "integer"
      +            },
      +            "name": {
      +              "description": "Tier name, e.g. 'Gold', 'Silver'",
      +              "maxLength": 30,
      +              "type": "string"
      +            },
      +            "threshold": {
      +              "description": "Minimum token balance for this tier",
      +              "exclusiveMinimum": 0,
      +              "type": "number"
      +            }
      +          },
      +          "required": [
      +            "name",
      +            "threshold",
      +            "discount"
      +          ],
      +          "type": "object"
      +        },
      +        "maxItems": 4,
      +        "minItems": 1,
      +        "type": "array"
      +      }
      +    },
      +    "required": [
      +      "symbol",
      +      "chainId",
      +      "contractAddress",
      +      "decimals",
      +      "tiers"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • addedInput schema / properties / partnerTokens / maxItems
      Added value: +8
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "http://json-schema.org/draft-07/schema#",
      +  "additionalProperties": true,
      +  "properties": {
      +    "data": {
      +      "description": "The endpoint's payload: a signed attestation, trust profile, discount, merchant or token records"
      +    },
      +    "error": {
      +      "description": "Error details when ok is false"
      +    },
      +    "items": {
      +      "description": "The result when the endpoint returns a JSON array",
      +      "items": {},
      +      "type": "array"
      +    },
      +    "keys": {
      +      "description": "JWKS entries (insumer_jwks)",
      +      "items": {},
      +      "type": "array"
      +    },
      +    "message": {
      +      "description": "A plain-text result (insumer_setup), or a message from the API"
      +    },
      +    "meta": {
      +      "description": "Response metadata such as version and timestamp"
      +    },
      +    "ok": {
      +      "description": "true when the API call succeeded",
      +      "type": "boolean"
      +    }
      +  },
      +  "type": "object"
      +}
  3. Addedv0.1.0

TDQS

A3.8/5.0
Behavior4/5

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, but the description adds real behavioral context: the operation replaces existing config, is capped at a max of 8 tokens, requires ownership, and refuses decimal discount values. That owner-only authorization constraint and the replace-destroys-prior-state detail are not derivable from the annotations alone.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

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

Five short sentences with zero filler, front-loading the verb/resource and the destructive replace semantic before the numeric limits and the authorization requirement. Every sentence carries a distinct constraint.

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?

An output schema exists so return values need no explanation, and the description covers the replace risk, ownership, token count cap and discount validation. It is slightly thin on what a validation failure or partial alsoOn removal looks like, though the schema's alsoOn note partially covers the latter.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents id, ownToken, partnerTokens and all nested constraints, including the 1-50 whole-number discount and the 8-item cap. The description restates the 8-token maximum and discount rule without adding syntax or format detail beyond the schema, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Configure merchant token discount tiers') and names the two sub-resources it writes (own token and partner tokens). The title's '(replaces)' flag is reinforced in the body, so the agent understands this is an overwrite, not an append. It does not name distinct siblings such as insumer_configure_nfts or insumer_configure_settings, so sibling disambiguation is left to the resource noun.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

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

Usage is implied by the resource and the 'Owner only' note, but the description never says when to prefer this over insumer_configure_nfts/insumer_configure_settings, nor when to skip it entirely. There is no explicit when-not guidance or named alternative, leaving the agent to infer the context.

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