Skip to main content
Glama

get_card_data

Get card details

Returns the current status and details of card orders. If card_id is provided, returns a single card, looked up across U.S. non-reloadable, international non-reloadable, and reloadable cards. If omitted, returns all cards of the given card_type for the authenticated user; card_type defaults to Non-Reloadable U.S. when omitted, so existing callers see unchanged behavior. Pass card_type=Non-Reloadable International to list international cards, or card_type=Reloadable to list reloadable cards.

For U.S. non-reloadable cards, details take ~7-10 seconds to become available after ordering; poll every 2-3 seconds until status is "ready", then read card_details. For international non-reloadable cards, the order is queued until an admin fulfills it (typically within 24 hours), after which card_details is populated.

For international cards, the card_id returned by /order-intl-card is a queue id. After admin fulfillment, the issuer's transaction id becomes the new card_id and the original queue id is preserved on the card as queued_order_card_id. You can keep polling /get-card-data?card_id=<original-queue-id> and it will resolve to the fulfilled card.

Reloadable cards are a separate product, set up by the account holder in the Laso dashboard rather than ordered through this API. They are reusable (a multi_use card stays open across charges until its limit is spent) and can be topped up, unlike the single-load non-reloadable cards. Listing them returns balance, spend_limit, last4, expiry, and reusable. If the wallet has no card issuer account linked, the list is empty and a note explains how the holder sets one up.

Reading a reloadable card's number and CVV is gated by the card issuer, and which gate applies depends on who issued it. Request the card by card_id; the response carries exactly one of three fields. card_details is the normal result for a card created through /create-reloadable-card, which Laso issues on the holder's behalf and can read for them directly — no approval step is involved. details_approval with status: "pending" and an approval_id appears only for a card the holder created in a DIFFERENT app: the issuer has emailed them an approve/deny link, and once they approve you retry as GET /get-card-data?card_id=<CARD_ID>&approval_id=<APPROVAL_ID> to receive card_details. details_error means the issuer could not return the number; retry shortly, and if it persists the holder can read the card in the dashboard. Spend the card by entering its number, expiry, and CVV at the merchant's checkout. billing_address is null on these cards and always will be — the issuer holds no billing address for a card. If a merchant requires one, use the address the account holder gave at identity verification (ask them; do not guess), since these cards are AVS-checked against it and a mismatch is the most common decline on a card that has funds. A card with reusable: true stays open after an approved charge and can be spent again up to its remaining balance; a charge larger than the balance is declined in full, as there are no partial approvals.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
card_idNoThe card ID returned from `/get-card` or `/order-intl-card`, or a reloadable card's id from `card_type=Reloadable`. Looked up across all three card types. If omitted, returns all cards of `card_type`.
card_typeNoWhen listing all cards (no `card_id`), filters by card type. Defaults to `Non-Reloadable U.S.` if omitted (preserves existing client behavior). Pass `Non-Reloadable International` to list international cards, or `Reloadable` to list reloadable cards.Non-Reloadable U.S.
auth_tokenNoLaso credential. Only if the MCP connection has no Authorization header.
approval_idNoReloadable cards only, and only for a card the account holder created in a DIFFERENT app: pass the approval_id from a prior details_approval response once they have approved it. Cards created through /create-reloadable-card are Laso-issued and never require this.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -{
      -  "anyOf": [
      -    {
      -      "description": "Response from `/get-card-data`. Three card types share this shape and each populates a different subset.\n\n**Non-reloadable (U.S. and International):** when `status` is `ready`, `card_details` carries the number, CVV, and expiry. International cards add `label`, `charged_usd_amount`, `fees_paid`, `state`, `balance_update_requested_timestamp`, and `queued_order_card_id`.\n\n**Reloadable:** returns `last4`, `expiry`, `balance`, `spend_limit`, `reusable`, `issuer_status`, `created_at`, and `expires_at` instead of the `usd_amount`/`timestamp` fields above. Reading its number and CVV is gated by the card issuer, so exactly one of `card_details`, `details_approval`, or `details_error` is present on a single-card lookup.",
      -      "properties": {
      -        "balance": {
      -          "description": "Reloadable cards only. Spendable balance in dollars.",
      -          "type": [
      -            "number",
      -            "null"
      -          ]
      -        },
      -        "balance_update_requested_timestamp": {
      -          "description": "International cards only. Unix timestamp (ms) of an outstanding admin balance update request, or null if none is pending.",
      -          "type": [
      -            "number",
      -            "null"
      -          ]
      -        },
      -        "card_details": {
      -          "description": "Only present when status is `ready` (U.S.) or `complete` (international).",
      -          "properties": {
      -            "available_balance": {
      -              "type": [
      -                "number",
      -                "null"
      -              ]
      -            },
      -            "billing_address": {
      -              "description": "The card billing address to enter when a merchant asks for one at checkout. The billing name is always `Laso Finance`. For USA non-reloadable cards `required` is `false` (any valid U.S. billing address works; this is a known-good default). For international non-reloadable cards `required` is `true` and the merchant AVS check is validated against exactly this address. On reloadable cards this is always null: the card issuer holds no billing address for a card, and they are AVS-checked against the address the account holder gave at their own identity verification. Ask the holder for it; do not substitute Laso's address.",
      -              "properties": {
      -                "city": {
      -                  "type": [
      -                    "string",
      -                    "null"
      -                  ]
      -                },
      -                "country": {
      -                  "type": [
      -                    "string",
      -                    "null"
      -                  ]
      -                },
      -                "line_1": {
      -                  "type": [
      -                    "string",
      -                    "null"
      -                  ]
      -                },
      -                "line_2": {
      -                  "type": [
      -                    "string",
      -                    "null"
      -                  ]
      -                },
      -                "name": {
      -                  "description": "Always `Laso Finance`.",
      -                  "type": [
      -                    "string",
      -                    "null"
      -                  ]
      -                },
      -                "note": {
      -                  "type": [
      -                    "string",
      -                    "null"
      -                  ]
      -                },
      -                "required": {
      -                  "description": "`true` if the card enforces AVS against this exact address (international cards); `false` if any valid U.S. address works (USA cards).",
      -                  "type": [
      -                    "boolean",
      -                    "null"
      -                  ]
      -                },
      -                "state": {
      -                  "type": [
      -                    "string",
      -                    "null"
      -                  ]
      -                },
      -                "zip": {
      -                  "type": [
      -                    "string",
      -                    "null"
      -                  ]
      -                }
      -              },
      -              "type": [
      -                "object",
      -                "null"
      -              ]
      -            },
      -            "card_number": {
      -              "type": [
      -                "string",
      -                "null"
      -              ]
      -            },
      -            "cvv": {
      -              "type": [
      -                "string",
      -                "null"
      -              ]
      -            },
      -            "exp_month": {
      -              "type": [
      -                "string",
      -                "null"
      -              ]
      -            },
      -            "exp_year": {
      -              "type": [
      -                "string",
      -                "null"
      -              ]
      -            }
      -          },
      -          "type": [
      -            "object",
      -            "null"
      -          ]
      -        },
      -        "card_id": {
      -          "type": [
      -            "string",
      -            "null"
      -          ]
      -        },
      -        "card_type": {
      -          "description": "One of: Non-Reloadable U.S., Non-Reloadable International, Reloadable.",
      -          "type": [
      -            "string",
      -            "null"
      -          ]
      -        },
      -        "charged_usd_amount": {
      -          "description": "International cards only. Amount the user was charged including fees.",
      -          "type": [
      -            "number",
      -            "null"
      -          ]
      -        },
      -        "country": {
      -          "description": "U.S. cards only.",
      -          "type": [
      -            "string",
      -            "null"
      -          ]
      -        },
      -        "created_at": {
      -          "description": "Reloadable cards only. Epoch milliseconds.",
      -          "type": [
      -            "number",
      -            "null"
      -          ]
      -        },
      -        "details_approval": {
      -          "description": "Reloadable cards only, and only for a card the holder created in ANOTHER app. The issuer has emailed them an approve/deny link; retry with `approval_id` once they approve. Cards created through `/create-reloadable-card` are Laso-issued and never take this path.",
      -          "properties": {
      -            "approval_id": {
      -              "type": [
      -                "string",
      -                "null"
      -              ]
      -            },
      -            "note": {
      -              "type": [
      -                "string",
      -                "null"
      -              ]
      -            },
      -            "status": {
      -              "description": "One of: pending.",
      -              "type": [
      -                "string",
      -                "null"
      -              ]
      -            }
      -          },
      -          "type": [
      -            "object",
      -            "null"
      -          ]
      -        },
      -        "details_error": {
      -          "description": "Reloadable cards only. Present when the issuer could not return the number, so a card with no `card_details` is never silently indistinguishable from one whose details are pending.",
      -          "type": [
      -            "string",
      -            "null"
      -          ]
      -        },
      -        "expires_at": {
      -          "description": "Reloadable cards only. Epoch milliseconds, or null when the card does not expire.",
      -          "type": [
      -            "number",
      -            "null"
      -          ]
      -        },
      -        "expiry": {
      -          "description": "Reloadable cards only. MM/YY.",
      -          "type": [
      -            "string",
      -            "null"
      -          ]
      -        },
      -        "fees_paid": {
      -          "description": "International cards only. Fees paid for this card.",
      -          "type": [
      -            "number",
      -            "null"
      -          ]
      -        },
      -        "issuer_status": {
      -          "description": "Reloadable cards only. The issuer's own status string, kept verbatim.",
      -          "type": [
      -            "string",
      -            "null"
      -          ]
      -        },
      -        "label": {
      -          "description": "International cards only. User-supplied label, may be empty.",
      -          "type": [
      -            "string",
      -            "null"
      -          ]
      -        },
      -        "last4": {
      -          "description": "Reloadable cards only. Last four digits.",
      -          "type": [
      -            "string",
      -            "null"
      -          ]
      -        },
      -        "last_updated_timestamp": {
      -          "description": "U.S. cards only. Unix timestamp (ms) of the last time card data was refreshed.",
      -          "type": [
      -            "number",
      -            "null"
      -          ]
      -        },
      -        "queued_order_card_id": {
      -          "description": "International cards only. The original `card_id` returned by `/order-intl-card`. After admin fulfillment the card is reissued with a new `card_id` (the issuer's transaction id); querying `/get-card-data?card_id=<original>` continues to resolve to the fulfilled card via this field.",
      -          "type": [
      -            "string",
      -            "null"
      -          ]
      -        },
      -        "reusable": {
      -          "description": "Reloadable cards only. True for a multi-use card.",
      -          "type": [
      -            "boolean",
      -            "null"
      -          ]
      -        },
      -        "spend_limit": {
      -          "description": "Reloadable cards only. Spend cap in dollars.",
      -          "type": [
      -            "number",
      -            "null"
      -          ]
      -        },
      -        "state": {
      -          "description": "International cards only. Raw card state. One of: queued, redeemable, complete, refund-requested, refund-requested-approved-for-queue, archived, refunded.",
      -          "type": [
      -            "string",
      -            "null"
      -          ]
      -        },
      -        "status": {
      -          "description": "One of: pending, ready, queued, complete, refund-requested, refunded, archived.",
      -          "type": [
      -            "string",
      -            "null"
      -          ]
      -        },
      -        "timestamp": {
      -          "type": [
      -            "number",
      -            "null"
      -          ]
      -        },
      -        "timestamp_readable": {
      -          "type": [
      -            "string",
      -            "null"
      -          ]
      -        },
      -        "transactions": {
      -          "description": "Card transaction history. U.S. and international cards use slightly different shapes — see `CardTransaction` and `IntlCardTransaction`.",
      -          "items": {
      -            "anyOf": [
      -              {
      -                "description": "U.S. prepaid card transaction.",
      -                "properties": {
      -                  "amount": {
      -                    "type": [
      -                      "number",
      -                      "null"
      -                    ]
      -                  },
      -                  "date": {
      -                    "type": [
      -                      "string",
      -                      "null"
      -                    ]
      -                  },
      -                  "description": {
      -                    "type": [
      -                      "string",
      -                      "null"
      -                    ]
      -                  },
      -                  "is_credit": {
      -                    "type": [
      -                      "boolean",
      -                      "null"
      -                    ]
      -                  }
      -                },
      -                "type": [
      -                  "object",
      -                  "null"
      -                ]
      -              },
      -              {
      -                "description": "International prepaid card transaction.",
      -                "properties": {
      -                  "amount": {
      -                    "description": "Transaction amount in USD.",
      -                    "type": [
      -                      "number",
      -                      "null"
      -                    ]
      -                  },
      -                  "date": {
      -                    "description": "Unix timestamp (ms) of the transaction.",
      -                    "type": [
      -                      "number",
      -                      "null"
      -                    ]
      -                  },
      -                  "merchant": {
      -                    "type": [
      -                      "string",
      -                      "null"
      -                    ]
      -                  },
      -                  "status": {
      -                    "description": "Optional status, e.g. `pending`.",
      -                    "type": [
      -                      "string",
      -                      "null"
      -                    ]
      -                  }
      -                },
      -                "type": [
      -                  "object",
      -                  "null"
      -                ]
      -              }
      -            ]
      -          },
      -          "type": [
      -            "array",
      -            "null"
      -          ]
      -        },
      -        "usd_amount": {
      -          "type": [
      -            "number",
      -            "null"
      -          ]
      -        }
      -      },
      -      "type": "object"
      -    },
      -    {
      -      "properties": {
      -        "cards": {
      -          "items": {
      -            "description": "Response from `/get-card-data`. Three card types share this shape and each populates a different subset.\n\n**Non-reloadable (U.S. and International):** when `status` is `ready`, `card_details` carries the number, CVV, and expiry. International cards add `label`, `charged_usd_amount`, `fees_paid`, `state`, `balance_update_requested_timestamp`, and `queued_order_card_id`.\n\n**Reloadable:** returns `last4`, `expiry`, `balance`, `spend_limit`, `reusable`, `issuer_status`, `created_at`, and `expires_at` instead of the `usd_amount`/`timestamp` fields above. Reading its number and CVV is gated by the card issuer, so exactly one of `card_details`, `details_approval`, or `details_error` is present on a single-card lookup.",
      -            "properties": {
      -              "balance": {
      -                "description": "Reloadable cards only. Spendable balance in dollars.",
      -                "type": [
      -                  "number",
      -                  "null"
      -                ]
      -              },
      -              "balance_update_requested_timestamp": {
      -                "description": "International cards only. Unix timestamp (ms) of an outstanding admin balance update request, or null if none is pending.",
      -                "type": [
      -                  "number",
      -                  "null"
      -                ]
      -              },
      -              "card_details": {
      -                "description": "Only present when status is `ready` (U.S.) or `complete` (international).",
      -                "properties": {
      -                  "available_balance": {
      -                    "type": [
      -                      "number",
      -                      "null"
      -                    ]
      -                  },
      -                  "billing_address": {
      -                    "description": "The card billing address to enter when a merchant asks for one at checkout. The billing name is always `Laso Finance`. For USA non-reloadable cards `required` is `false` (any valid U.S. billing address works; this is a known-good default). For international non-reloadable cards `required` is `true` and the merchant AVS check is validated against exactly this address. On reloadable cards this is always null: the card issuer holds no billing address for a card, and they are AVS-checked against the address the account holder gave at their own identity verification. Ask the holder for it; do not substitute Laso's address.",
      -                    "properties": {
      -                      "city": {
      -                        "type": [
      -                          "string",
      -                          "null"
      -                        ]
      -                      },
      -                      "country": {
      -                        "type": [
      -                          "string",
      -                          "null"
      -                        ]
      -                      },
      -                      "line_1": {
      -                        "type": [
      -                          "string",
      -                          "null"
      -                        ]
      -                      },
      -                      "line_2": {
      -                        "type": [
      -                          "string",
      -                          "null"
      -                        ]
      -                      },
      -                      "name": {
      -                        "description": "Always `Laso Finance`.",
      -                        "type": [
      -                          "string",
      -                          "null"
      -                        ]
      -                      },
      -                      "note": {
      -                        "type": [
      -                          "string",
      -                          "null"
      -                        ]
      -                      },
      -                      "required": {
      -                        "description": "`true` if the card enforces AVS against this exact address (international cards); `false` if any valid U.S. address works (USA cards).",
      -                        "type": [
      -                          "boolean",
      -                          "null"
      -                        ]
      -                      },
      -                      "state": {
      -                        "type": [
      -                          "string",
      -                          "null"
      -                        ]
      -                      },
      -                      "zip": {
      -                        "type": [
      -                          "string",
      -                          "null"
      -                        ]
      -                      }
      -                    },
      -                    "type": [
      -                      "object",
      -                      "null"
      -                    ]
      -                  },
      -                  "card_number": {
      -                    "type": [
      -                      "string",
      -                      "null"
      -                    ]
      -                  },
      -                  "cvv": {
      -                    "type": [
      -                      "string",
      -                      "null"
      -                    ]
      -                  },
      -                  "exp_month": {
      -                    "type": [
      -                      "string",
      -                      "null"
      -                    ]
      -                  },
      -                  "exp_year": {
      -                    "type": [
      -                      "string",
      -                      "null"
      -                    ]
      -                  }
      -                },
      -                "type": [
      -                  "object",
      -                  "null"
      -                ]
      -              },
      -              "card_id": {
      -                "type": [
      -                  "string",
      -                  "null"
      -                ]
      -              },
      -              "card_type": {
      -                "description": "One of: Non-Reloadable U.S., Non-Reloadable International, Reloadable.",
      -                "type": [
      -                  "string",
      -                  "null"
      -                ]
      -              },
      -              "charged_usd_amount": {
      -                "description": "International cards only. Amount the user was charged including fees.",
      -                "type": [
      -                  "number",
      -                  "null"
      -                ]
      -              },
      -              "country": {
      -                "description": "U.S. cards only.",
      -                "type": [
      -                  "string",
      -                  "null"
      -                ]
      -              },
      -              "created_at": {
      -                "description": "Reloadable cards only. Epoch milliseconds.",
      -                "type": [
      -                  "number",
      -                  "null"
      -                ]
      -              },
      -              "details_approval": {
      -                "description": "Reloadable cards only, and only for a card the holder created in ANOTHER app. The issuer has emailed them an approve/deny link; retry with `approval_id` once they approve. Cards created through `/create-reloadable-card` are Laso-issued and never take this path.",
      -                "properties": {
      -                  "approval_id": {
      -                    "type": [
      -                      "string",
      -                      "null"
      -                    ]
      -                  },
      -                  "note": {
      -                    "type": [
      -                      "string",
      -                      "null"
      -                    ]
      -                  },
      -                  "status": {
      -                    "description": "One of: pending.",
      -                    "type": [
      -                      "string",
      -                      "null"
      -                    ]
      -                  }
      -                },
      -                "type": [
      -                  "object",
      -                  "null"
      -                ]
      -              },
      -              "details_error": {
      -                "description": "Reloadable cards only. Present when the issuer could not return the number, so a card with no `card_details` is never silently indistinguishable from one whose details are pending.",
      -                "type": [
      -                  "string",
      -                  "null"
      -                ]
      -              },
      -              "expires_at": {
      -                "description": "Reloadable cards only. Epoch milliseconds, or null when the card does not expire.",
      -                "type": [
      -                  "number",
      -                  "null"
      -                ]
      -              },
      -              "expiry": {
      -                "description": "Reloadable cards only. MM/YY.",
      -                "type": [
      -                  "string",
      -                  "null"
      -                ]
      -              },
      -              "fees_paid": {
      -                "description": "International cards only. Fees paid for this card.",
      -                "type": [
      -                  "number",
      -                  "null"
      -                ]
      -              },
      -              "issuer_status": {
      -                "description": "Reloadable cards only. The issuer's own status string, kept verbatim.",
      -                "type": [
      -                  "string",
      -                  "null"
      -                ]
      -              },
      -              "label": {
      -                "description": "International cards only. User-supplied label, may be empty.",
      -                "type": [
      -                  "string",
      -                  "null"
      -                ]
      -              },
      -              "last4": {
      -                "description": "Reloadable cards only. Last four digits.",
      -                "type": [
      -                  "string",
      -                  "null"
      -                ]
      -              },
      -              "last_updated_timestamp": {
      -                "description": "U.S. cards only. Unix timestamp (ms) of the last time card data was refreshed.",
      -                "type": [
      -                  "number",
      -                  "null"
      -                ]
      -              },
      -              "queued_order_card_id": {
      -                "description": "International cards only. The original `card_id` returned by `/order-intl-card`. After admin fulfillment the card is reissued with a new `card_id` (the issuer's transaction id); querying `/get-card-data?card_id=<original>` continues to resolve to the fulfilled card via this field.",
      -                "type": [
      -                  "string",
      -                  "null"
      -                ]
      -              },
      -              "reusable": {
      -                "description": "Reloadable cards only. True for a multi-use card.",
      -                "type": [
      -                  "boolean",
      -                  "null"
      -                ]
      -              },
      -              "spend_limit": {
      -                "description": "Reloadable cards only. Spend cap in dollars.",
      -                "type": [
      -                  "number",
      -                  "null"
      -                ]
      -              },
      -              "state": {
      -                "description": "International cards only. Raw card state. One of: queued, redeemable, complete, refund-requested, refund-requested-approved-for-queue, archived, refunded.",
      -                "type": [
      -                  "string",
      -                  "null"
      -                ]
      -              },
      -              "status": {
      -                "description": "One of: pending, ready, queued, complete, refund-requested, refunded, archived.",
      -                "type": [
      -                  "string",
      -                  "null"
      -                ]
      -              },
      -              "timestamp": {
      -                "type": [
      -                  "number",
      -                  "null"
      -                ]
      -              },
      -              "timestamp_readable": {
      -                "type": [
      -                  "string",
      -                  "null"
      -                ]
      -              },
      -              "transactions": {
      -                "description": "Card transaction history. U.S. and international cards use slightly different shapes — see `CardTransaction` and `IntlCardTransaction`.",
      -                "items": {
      -                  "anyOf": [
      -                    {
      -                      "description": "U.S. prepaid card transaction.",
      -                      "properties": {
      -                        "amount": {
      -                          "type": [
      -                            "number",
      -                            "null"
      -                          ]
      -                        },
      -                        "date": {
      -                          "type": [
      -                            "string",
      -                            "null"
      -                          ]
      -                        },
      -                        "description": {
      -                          "type": [
      -                            "string",
      -                            "null"
      -                          ]
      -                        },
      -                        "is_credit": {
      -                          "type": [
      -                            "boolean",
      -                            "null"
      -                          ]
      -                        }
      -                      },
      -                      "type": [
      -                        "object",
      -                        "null"
      -                      ]
      -                    },
      -                    {
      -                      "description": "International prepaid card transaction.",
      -                      "properties": {
      -                        "amount": {
      -                          "description": "Transaction amount in USD.",
      -                          "type": [
      -                            "number",
      -                            "null"
      -                          ]
      -                        },
      -                        "date": {
      -                          "description": "Unix timestamp (ms) of the transaction.",
      -                          "type": [
      -                            "number",
      -                            "null"
      -                          ]
      -                        },
      -                        "merchant": {
      -                          "type": [
      -                            "string",
      -                            "null"
      -                          ]
      -                        },
      -                        "status": {
      -                          "description": "Optional status, e.g. `pending`.",
      -                          "type": [
      -                            "string",
      -                            "null"
      -                          ]
      -                        }
      -                      },
      -                      "type": [
      -                        "object",
      -                        "null"
      -                      ]
      -                    }
      -                  ]
      -                },
      -                "type": [
      -                  "array",
      -                  "null"
      -                ]
      -              },
      -              "usd_amount": {
      -                "type": [
      -                  "number",
      -                  "null"
      -                ]
      -              }
      -            },
      -            "type": [
      -              "object",
      -              "null"
      -            ]
      -          },
      -          "type": [
      -            "array",
      -            "null"
      -          ]
      -        }
      -      },
      -      "type": "object"
      -    }
      -  ],
      -  "type": "object"
      -}New value: +null
  2. First observed

TDQS

A4.5/5.0
Behavior5/5

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

With no annotations to fall back on, the description carries the full burden and fully delivers: it discloses timing windows (7-10 seconds, ~24 hours), polling guidance, the queue-id-to-card-id lifecycle for international orders, the three-way reloadable card result (card_details/details_approval/details_error), and the perpetual null billing_address with AVS implications. It also clarifies that no approval step is involved for Laso-issued reloadable cards, preventing a false assumption.

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 description is long, but it is organized by card type and front-loads the core behavior before special cases. A few sentences, such as the merchant checkout guidance, are arguably beyond what an API invocation requires, but most paragraphs earn their place given the complex multi-state behavior being documented.

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?

Given there is no output schema and no annotations, the description is notably complete: it names the key response fields, statuses, polling cadence, empty-list behavior with explanatory note, and error/approval states. An agent has the information needed to decide when to call the tool and how to handle the response without additional lookup.

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

Parameters5/5

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

Even though schema coverage is 100%, the description materially enriches the parameters: it explains card_id can be a queue id that resolves after fulfillment, card_type values map to distinct product behaviors, and approval_id is only valid in the specific 'different app' scenario. This goes well beyond the schema's baseline descriptions.

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?

The description clearly identifies the operation ('Get card details') and resource ('card orders'), and specifies the single-vs-list behavior plus the three card types it covers. However, it does not explicitly differentiate itself from sibling tools like get_card or refresh_card_data, so it stops short of full sibling differentiation.

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

Usage Guidelines4/5

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

Provides very clear contextual guidance: use card_id for a single lookup, list by card_type with a default preserving old behavior, poll every 2-3 seconds for U.S. cards, and pass approval_id only for the described reloadable-card approval flow. It does not explicitly state when not to use this tool or name alternatives such as refresh_card_data, but the usage context is unambiguous.

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.

Resources