{
  "server": "com.agentrefills/giftcards",
  "endpoint": "https://mcp.agentrefills.com/mcp",
  "transport": "streamable-http",
  "description": "Machine-readable manifest of the five AgentRefills MCP tools. Mirrors what the server returns from tools/list. Amounts are integer minor units (cents). Errors use a closed taxonomy; every error carries an agent-actionable hint.",
  "tools": [
    {
      "name": "list_brands",
      "title": "Search gift-card brands",
      "description": "Search purchasable brands by query, country, and category. Returns brand ids, denominations, and stock. Read-only; safe to call repeatedly.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": {"type": "string", "description": "Free-text brand search, e.g. \"amazon\"."},
          "country": {"type": "string", "description": "ISO-3166-1 alpha-2 code.", "default": "US"},
          "category": {"type": "string", "description": "Optional category filter, e.g. \"gaming\"."},
          "limit": {"type": "integer", "default": 20, "maximum": 50, "minimum": 1}
        }
      },
      "annotations": {"title": "Search gift-card brands", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": true}
    },
    {
      "name": "buy_giftcard",
      "title": "Buy a gift card",
      "description": "Start an async purchase. Returns a task_id immediately. Under the spend cap it settles automatically; at or above the approval threshold it parks for human approval. Re-using client_ref returns the existing task and never charges twice.",
      "inputSchema": {
        "type": "object",
        "required": ["brand_id", "amount_minor", "currency"],
        "properties": {
          "brand_id": {"type": "string", "description": "A brand_id from list_brands."},
          "amount_minor": {"type": "integer", "minimum": 1, "description": "Value in integer minor units (cents). 2500 = $25.00."},
          "currency": {"type": "string", "default": "USD"},
          "country": {"type": "string", "description": "ISO-3166-1 alpha-2; defaults to the key's region."},
          "client_ref": {"type": "string", "description": "Idempotency key. Re-use returns the existing task."},
          "metadata": {"type": "object", "additionalProperties": true}
        }
      },
      "annotations": {"title": "Buy a gift card", "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": true}
    },
    {
      "name": "get_code",
      "title": "Release the redemption code",
      "description": "Release the code, link, or PIN for a completed purchase exactly once, and log the access. A second call returns ALREADY_RELEASED. Only the purchasing agent may call it. Raw codes are never logged or traced.",
      "inputSchema": {
        "type": "object",
        "required": ["task_id"],
        "properties": {
          "task_id": {"type": "string", "format": "uuid", "description": "The task_id returned by buy_giftcard."}
        }
      },
      "annotations": {"title": "Release the redemption code", "readOnlyHint": false, "destructiveHint": true, "idempotentHint": false, "openWorldHint": false}
    },
    {
      "name": "check_balance",
      "title": "Check budget and status",
      "description": "The calling agent's remaining budget, daily and monthly limits, float cover, and kill-switch state. Read-only.",
      "inputSchema": {"type": "object", "properties": {}},
      "annotations": {"title": "Check budget and status", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false}
    },
    {
      "name": "request_approval",
      "title": "Re-ping the human approver",
      "description": "Re-ping the human approver for a task parked in APPROVAL_REQUIRED. Rate-limited to one per task per hour.",
      "inputSchema": {
        "type": "object",
        "required": ["task_id", "reason"],
        "properties": {
          "task_id": {"type": "string", "format": "uuid"},
          "reason": {"type": "string", "maxLength": 500}
        }
      },
      "annotations": {"title": "Re-ping the human approver", "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false}
    }
  ],
  "errors": ["POLICY_DENIED", "BUDGET_EXCEEDED", "APPROVAL_REQUIRED", "APPROVAL_REJECTED", "OUT_OF_STOCK", "PAYMENT_FAILED", "INVOICE_EXPIRED", "PROVIDER_HOLD", "ALREADY_RELEASED", "NOT_FOUND", "UNAUTHORIZED", "RETRYABLE"]
}