{
  "tools": [
    {
      "name": "get_payment_agreement",
      "description": "Retrieve payment agreement details, state transitions, and AI-facing summary guidance.",
      "method": "POST",
      "endpoint": "/tools/execute",
      "auth": {
        "required": true,
        "header": "Authorization",
        "accepted_formats": [
          "sbp_live_xxx",
          "Bearer sbp_live_xxx"
        ]
      },
      "response_contract": "StandardResponse<T> with success, data, metadata, insights, summary",
      "output_schema": {
        "type": "object",
        "required": [
          "success",
          "timestamp",
          "data",
          "metadata",
          "insights",
          "summary"
        ],
        "additionalProperties": true,
        "properties": {
          "success": {
            "type": "boolean"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "data": {
            "type": "object"
          },
          "metadata": {
            "type": "object"
          },
          "insights": {
            "type": "object"
          },
          "summary": {
            "type": "string"
          },
          "raw": {}
        },
        "notes": "Set include_raw=true to include optional raw upstream response payload."
      },
      "error_schema": {
        "type": "object",
        "required": [
          "error",
          "message"
        ],
        "additionalProperties": true,
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "request_id": {
            "type": "string"
          },
          "retryable": {
            "type": "boolean"
          }
        }
      },
      "error_model": {
        "domain_errors": [
          {
            "code": "RESOURCE_NOT_FOUND",
            "retryable": false,
            "suggested_next_tool": "create_payment_agreement"
          },
          {
            "code": "INVALID_REQUEST",
            "retryable": false,
            "suggested_next_tool": null
          }
        ]
      },
      "openapi_operation": {
        "method": "get",
        "path": "/api/public/payment_agreement"
      },
      "output_openapi_schema_ref": "#/components/schemas/SuccessPaymentAgreementResponse",
      "required_arguments": [
        "payment_agreement_id"
      ],
      "optional_arguments": [
        "enrich",
        "include_raw"
      ],
      "argument_hints": {
        "payment_agreement_id": "String ID returned by create_payment_agreement, e.g. 2882PA20251227045450257",
        "enrich": "Boolean, defaults true. Include business guidance for agent decisions.",
        "include_raw": "Boolean, defaults false. Include raw upstream API payload for debugging only."
      },
      "argument_schema": {
        "payment_agreement_id": {
          "type": "string",
          "pattern": "^[0-9]+PA[0-9]+$"
        },
        "enrich": {
          "type": "boolean",
          "default": true
        },
        "include_raw": {
          "type": "boolean",
          "default": false
        }
      },
      "example": {
        "tool": "get_payment_agreement",
        "arguments": {
          "payment_agreement_id": "2882PA20251227045450257"
        }
      },
      "decision_guidance": {
        "when_to_use": "Use when you have a payment agreement ID and need latest status/details.",
        "preconditions": [
          "Valid payment_agreement_id"
        ],
        "retryable_errors": [
          "AUTH_MISSING_OR_INVALID"
        ],
        "non_retryable_errors": [
          "RESOURCE_NOT_FOUND",
          "INVALID_REQUEST"
        ],
        "next_best_tool_on_failure": "create_payment_agreement"
      },
      "retry_policy": {
        "safe_to_retry": true,
        "retry_on_status": [
          401,
          429,
          500
        ],
        "backoff": "exponential_jitter"
      },
      "idempotency_notes": "Read-only operation; safe to repeat with same input.",
      "error_contract": [
        {
          "status": 400,
          "code": "INVALID_REQUEST",
          "when": "Malformed JSON or missing required field"
        },
        {
          "status": 401,
          "code": "AUTH_MISSING_OR_INVALID",
          "when": "Session/API key missing or invalid"
        },
        {
          "status": 403,
          "code": "TOOL_NOT_PERMITTED",
          "when": "Client policy blocks tool"
        },
        {
          "status": 404,
          "code": "RESOURCE_NOT_FOUND",
          "when": "Agreement ID not found"
        }
      ]
    },
    {
      "name": "create_payment_agreement",
      "description": "Create a new PayTo payment agreement for payer authorization and recurring collection.",
      "method": "POST",
      "endpoint": "/tools/execute",
      "auth": {
        "required": true,
        "header": "Authorization",
        "accepted_formats": [
          "sbp_live_xxx",
          "Bearer sbp_live_xxx"
        ]
      },
      "response_contract": "StandardResponse<T> with success, data, metadata, insights, summary",
      "output_schema": {
        "type": "object",
        "required": [
          "success",
          "timestamp",
          "data",
          "metadata",
          "insights",
          "summary"
        ],
        "additionalProperties": true,
        "properties": {
          "success": {
            "type": "boolean"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "data": {
            "type": "object"
          },
          "metadata": {
            "type": "object"
          },
          "insights": {
            "type": "object"
          },
          "summary": {
            "type": "string"
          },
          "raw": {}
        },
        "notes": "Set include_raw=true to include optional raw upstream response payload."
      },
      "error_schema": {
        "type": "object",
        "required": [
          "error",
          "message"
        ],
        "additionalProperties": true,
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "request_id": {
            "type": "string"
          },
          "retryable": {
            "type": "boolean"
          }
        }
      },
      "error_model": {
        "domain_errors": [
          {
            "code": "VALIDATION_OR_BUSINESS_RULE",
            "retryable": false,
            "suggested_next_tool": "get_payment_agreement"
          },
          {
            "code": "DEVELOPER_CREDITS_EXHAUSTED",
            "retryable": false,
            "suggested_next_tool": null
          }
        ]
      },
      "openapi_operation": {
        "method": "post",
        "path": "/api/public/payment_agreement"
      },
      "output_openapi_schema_ref": "#/components/schemas/SuccessPaymentAgreementResponse",
      "required_arguments": [
        "name",
        "type",
        "maximum_amount",
        "frequency",
        "number_of_transactions_permitted"
      ],
      "optional_arguments": [
        "pay_id",
        "phone_number",
        "bsb",
        "account_number",
        "agreement_type",
        "start_date",
        "end_date",
        "enrich",
        "include_raw"
      ],
      "argument_hints": {
        "type": "Allowed identifier types: email, phone, org, abn, or bsb.",
        "pay_id": "Required unless type=bsb.",
        "bsb": "Required with account_number when type=bsb.",
        "account_number": "Required with bsb when type=bsb.",
        "frequency": "Preferred stored codes: ADHO, DAIL, FRTN, INDA, MIAN, MNTH, QURT, WEEK, YEAR. Aliases DAILY and ADHOC are accepted by upstream.",
        "maximum_amount": "String amount in AUD, e.g. 35.00",
        "number_of_transactions_permitted": "Positive integer, e.g. 1"
      },
      "argument_schema": {
        "name": {
          "type": "string",
          "minLength": 1
        },
        "type": {
          "type": "string",
          "enum": [
            "email",
            "phone",
            "org",
            "abn",
            "bsb"
          ]
        },
        "maximum_amount": {
          "type": "string",
          "pattern": "^\\d+(\\.\\d{1,2})?$"
        },
        "frequency": {
          "type": "string",
          "enum": [
            "ADHO",
            "DAIL",
            "FRTN",
            "INDA",
            "MIAN",
            "MNTH",
            "QURT",
            "WEEK",
            "YEAR",
            "DAILY",
            "ADHOC"
          ]
        },
        "number_of_transactions_permitted": {
          "type": "integer",
          "minimum": 1
        },
        "pay_id": {
          "type": "string"
        },
        "bsb": {
          "type": [
            "string",
            "number"
          ]
        },
        "account_number": {
          "type": [
            "string",
            "number"
          ]
        },
        "conditional_requirements": [
          {
            "if": {
              "type": "bsb"
            },
            "then_required": [
              "bsb",
              "account_number"
            ]
          },
          {
            "if_not": {
              "type": "bsb"
            },
            "then_required": [
              "pay_id"
            ]
          }
        ]
      },
      "example": {
        "tool": "create_payment_agreement",
        "arguments": {
          "name": "Gym Membership",
          "type": "email",
          "maximum_amount": "35.00",
          "frequency": "MNTH",
          "number_of_transactions_permitted": 1,
          "pay_id": "payer@example.com"
        }
      },
      "decision_guidance": {
        "when_to_use": "Use to create a new payer authorization mandate before initiating payments.",
        "preconditions": [
          "name, type, maximum_amount, frequency, number_of_transactions_permitted"
        ],
        "retryable_errors": [
          "AUTH_MISSING_OR_INVALID"
        ],
        "non_retryable_errors": [
          "VALIDATION_OR_BUSINESS_RULE",
          "DEVELOPER_CREDITS_EXHAUSTED"
        ],
        "next_best_tool_on_failure": "get_payment_agreement"
      },
      "retry_policy": {
        "safe_to_retry": false,
        "retry_on_status": [
          401,
          429,
          500
        ],
        "backoff": "exponential_jitter"
      },
      "idempotency_notes": "Creates a new agreement and is not idempotent without caller-side deduplication.",
      "error_contract": [
        {
          "status": 400,
          "code": "INVALID_REQUEST",
          "when": "Missing or invalid input shape"
        },
        {
          "status": 401,
          "code": "AUTH_MISSING_OR_INVALID",
          "when": "Session/API key missing or invalid"
        },
        {
          "status": 402,
          "code": "DEVELOPER_CREDITS_EXHAUSTED",
          "when": "Developer credits are exhausted"
        },
        {
          "status": 422,
          "code": "VALIDATION_OR_BUSINESS_RULE",
          "when": "Upstream validation or business rule failure"
        }
      ]
    },
    {
      "name": "initiate_payment",
      "description": "Initiate a debit payment against an approved payment agreement.",
      "method": "POST",
      "endpoint": "/tools/execute",
      "auth": {
        "required": true,
        "header": "Authorization",
        "accepted_formats": [
          "sbp_live_xxx",
          "Bearer sbp_live_xxx"
        ]
      },
      "response_contract": "StandardResponse<T> with success, data, metadata, insights, summary",
      "output_schema": {
        "type": "object",
        "required": [
          "success",
          "timestamp",
          "data",
          "metadata",
          "insights",
          "summary"
        ],
        "additionalProperties": true,
        "properties": {
          "success": {
            "type": "boolean"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "data": {
            "type": "object"
          },
          "metadata": {
            "type": "object"
          },
          "insights": {
            "type": "object"
          },
          "summary": {
            "type": "string"
          },
          "raw": {}
        },
        "notes": "Set include_raw=true to include optional raw upstream response payload."
      },
      "error_schema": {
        "type": "object",
        "required": [
          "error",
          "message"
        ],
        "additionalProperties": true,
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "request_id": {
            "type": "string"
          },
          "retryable": {
            "type": "boolean"
          }
        }
      },
      "error_model": {
        "domain_errors": [
          {
            "code": "BUSINESS_RULE_FAILURE",
            "retryable": false,
            "suggested_next_tool": "get_payment_agreement"
          },
          {
            "code": "AGREEMENT_NOT_FOUND",
            "retryable": false,
            "suggested_next_tool": "create_payment_agreement"
          },
          {
            "code": "INVALID_AMOUNT_OR_REQUEST",
            "retryable": false,
            "suggested_next_tool": null
          }
        ]
      },
      "openapi_operation": {
        "method": "post",
        "path": "/api/public/payment_initiation"
      },
      "output_openapi_schema_ref": "#/components/schemas/SuccessPaymentInitiationResponse",
      "required_arguments": [
        "payment_agreement_id",
        "amount"
      ],
      "optional_arguments": [
        "idempotency_key",
        "merchant_reference",
        "notes",
        "description",
        "enrich",
        "include_raw"
      ],
      "argument_hints": {
        "amount": "Number or numeric string greater than zero, e.g. 10.00",
        "notes": "Optional note persisted by backend for this payment initiation.",
        "description": "Legacy alias; if notes is omitted, description is forwarded as notes."
      },
      "argument_schema": {
        "idempotency_key": {
          "type": "string",
          "pattern": "^[A-Za-z0-9._:-]{16,128}$"
        },
        "merchant_reference": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        },
        "payment_agreement_id": {
          "type": "string",
          "pattern": "^[0-9]+PA[0-9]+$"
        },
        "amount": {
          "oneOf": [
            {
              "type": "number",
              "exclusiveMinimum": 0
            },
            {
              "type": "string",
              "pattern": "^\\d+(\\.\\d{1,2})?$"
            }
          ]
        },
        "notes": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "enrich": {
          "type": "boolean",
          "default": true
        },
        "include_raw": {
          "type": "boolean",
          "default": false
        }
      },
      "example": {
        "tool": "initiate_payment",
        "arguments": {
          "payment_agreement_id": "2882PA20251227045450257",
          "amount": "10.00",
          "idempotency_key": "payment-invoice-4201-v1",
          "merchant_reference": "invoice-4201",
          "notes": "Invoice 4201"
        }
      },
      "decision_guidance": {
        "when_to_use": "Use to debit an already approved payment agreement.",
        "preconditions": [
          "Active payment_agreement_id",
          "amount > 0"
        ],
        "retryable_errors": [
          "AUTH_MISSING_OR_INVALID"
        ],
        "non_retryable_errors": [
          "BUSINESS_RULE_FAILURE",
          "AGREEMENT_NOT_FOUND",
          "INVALID_AMOUNT_OR_REQUEST"
        ],
        "next_best_tool_on_failure": "get_payment_agreement"
      },
      "retry_policy": {
        "safe_to_retry": false,
        "retry_on_status": [
          401,
          429,
          500
        ],
        "backoff": "exponential_jitter"
      },
      "idempotency_notes": "idempotency_key and merchant_reference are optional. When both are omitted, the existing payment path is used. When a key is sent, persist it with the merchant reference and reuse both after any uncertain outcome. The same merchant_reference can be used for another payment, including on a different agreement, when the Idempotency-Key is new. A new key skips only the duplicate cooldown. The amount checks, the daily amount limit, and the count of 10 non-invoice payments in the Sydney day still apply.",
      "error_contract": [
        {
          "status": 400,
          "code": "INVALID_AMOUNT_OR_REQUEST",
          "when": "Amount <= 0 or invalid request body"
        },
        {
          "status": 401,
          "code": "AUTH_MISSING_OR_INVALID",
          "when": "Session/API key missing or invalid"
        },
        {
          "status": 404,
          "code": "AGREEMENT_NOT_FOUND",
          "when": "Agreement does not exist for merchant"
        },
        {
          "status": 422,
          "code": "BUSINESS_RULE_FAILURE",
          "when": "Cooldown, inactive agreement, limits, or scheme rejection"
        }
      ]
    },
    {
      "name": "get_payment_operation",
      "description": "Retrieve the original payment operation after an uncertain outcome.",
      "method": "POST",
      "endpoint": "/tools/execute",
      "auth": {
        "required": true,
        "header": "Authorization",
        "accepted_formats": [
          "sbp_live_xxx",
          "Bearer sbp_live_xxx"
        ]
      },
      "response_contract": "StandardResponse<T> with success, data, metadata, insights, summary",
      "output_schema": {
        "type": "object",
        "required": [
          "success",
          "timestamp",
          "data",
          "metadata",
          "insights",
          "summary"
        ],
        "additionalProperties": true,
        "properties": {
          "success": {
            "type": "boolean"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "data": {
            "type": "object"
          },
          "metadata": {
            "type": "object"
          },
          "insights": {
            "type": "object"
          },
          "summary": {
            "type": "string"
          },
          "raw": {}
        },
        "notes": "Set include_raw=true to include optional raw upstream response payload."
      },
      "error_schema": {
        "type": "object",
        "required": [
          "error",
          "message"
        ],
        "additionalProperties": true,
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "request_id": {
            "type": "string"
          },
          "retryable": {
            "type": "boolean"
          }
        }
      },
      "error_model": {
        "domain_errors": [
          {
            "code": "RESOURCE_NOT_FOUND",
            "retryable": false,
            "suggested_next_tool": "initiate_payment"
          },
          {
            "code": "INVALID_REQUEST",
            "retryable": false,
            "suggested_next_tool": null
          }
        ]
      },
      "openapi_operation": {
        "method": "get",
        "path": "/api/public/payment_operations/{id}"
      },
      "required_arguments": [
        "operation_id"
      ],
      "optional_arguments": [],
      "argument_hints": {
        "operation_id": "Operation id returned with the original payment, e.g. op_contract."
      },
      "argument_schema": {
        "operation_id": {
          "type": "string",
          "pattern": "^op_[A-Za-z0-9-]+$"
        }
      },
      "example": {
        "tool": "get_payment_operation",
        "arguments": {
          "operation_id": "op_contract"
        }
      },
      "decision_guidance": {
        "when_to_use": "Use after a pending payment to read the original operation.",
        "preconditions": [
          "operation_id from the original initiate_payment response"
        ],
        "retryable_errors": [
          "AUTH_MISSING_OR_INVALID"
        ],
        "non_retryable_errors": [
          "RESOURCE_NOT_FOUND",
          "INVALID_REQUEST"
        ],
        "next_best_tool_on_failure": "initiate_payment"
      },
      "retry_policy": {
        "safe_to_retry": true,
        "retry_on_status": [
          401,
          429,
          500
        ],
        "backoff": "exponential_jitter"
      },
      "idempotency_notes": "Read-only. Reuse the original idempotency key and merchant reference. Do not create a new payment.",
      "error_contract": [
        {
          "status": 400,
          "code": "INVALID_REQUEST",
          "when": "operation_id is missing or has the wrong shape"
        },
        {
          "status": 401,
          "code": "AUTH_MISSING_OR_INVALID",
          "when": "Session/API key missing or invalid"
        },
        {
          "status": 404,
          "code": "RESOURCE_NOT_FOUND",
          "when": "Operation does not exist for this merchant"
        }
      ]
    },
    {
      "name": "get_payment_events",
      "description": "Read payment events for this merchant. The list stays empty until the webhook profile is signed_v2 or polling; the default legacy profile does not write these events. After one pending payment, use get_payment_operation with the original operation_id. Persist the cursor only after the events are processed successfully.",
      "method": "POST",
      "endpoint": "/tools/execute",
      "auth": {
        "required": true,
        "header": "Authorization",
        "accepted_formats": [
          "sbp_live_xxx",
          "Bearer sbp_live_xxx"
        ]
      },
      "response_contract": "StandardResponse<T> with success, data, metadata, insights, summary",
      "output_schema": {
        "type": "object",
        "required": [
          "success",
          "timestamp",
          "data",
          "metadata",
          "insights",
          "summary"
        ],
        "additionalProperties": true,
        "properties": {
          "success": {
            "type": "boolean"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "data": {
            "type": "object"
          },
          "metadata": {
            "type": "object"
          },
          "insights": {
            "type": "object"
          },
          "summary": {
            "type": "string"
          },
          "raw": {}
        },
        "notes": "Set include_raw=true to include optional raw upstream response payload."
      },
      "error_schema": {
        "type": "object",
        "required": [
          "error",
          "message"
        ],
        "additionalProperties": true,
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "request_id": {
            "type": "string"
          },
          "retryable": {
            "type": "boolean"
          }
        }
      },
      "error_model": {
        "domain_errors": [
          {
            "code": "INVALID_REQUEST",
            "retryable": false,
            "suggested_next_tool": null
          }
        ]
      },
      "openapi_operation": {
        "method": "get",
        "path": "/api/public/payment_events"
      },
      "required_arguments": [],
      "optional_arguments": [
        "cursor"
      ],
      "argument_hints": {
        "cursor": "Opaque cursor from the previous response. Persist it only after the events are processed successfully."
      },
      "argument_schema": {
        "cursor": {
          "type": "string",
          "maxLength": 4096
        }
      },
      "example": {
        "tool": "get_payment_events",
        "arguments": {}
      },
      "decision_guidance": {
        "when_to_use": "Use to read payment events after the webhook profile is signed_v2 or polling.",
        "preconditions": [
          "Merchant webhook profile is signed_v2 or polling"
        ],
        "retryable_errors": [
          "AUTH_MISSING_OR_INVALID"
        ],
        "non_retryable_errors": [
          "INVALID_REQUEST"
        ],
        "next_best_tool_on_failure": "get_payment_operation"
      },
      "retry_policy": {
        "safe_to_retry": true,
        "retry_on_status": [
          401,
          429,
          500
        ],
        "backoff": "exponential_jitter"
      },
      "idempotency_notes": "Read-only. The list stays empty on the default legacy webhook profile. A single pending payment is recovered with get_payment_operation.",
      "error_contract": [
        {
          "status": 400,
          "code": "INVALID_REQUEST",
          "when": "Cursor is invalid"
        },
        {
          "status": 401,
          "code": "AUTH_MISSING_OR_INVALID",
          "when": "Session/API key missing or invalid"
        }
      ]
    },
    {
      "name": "get_payment_initiation",
      "description": "Retrieve a payment initiation status by payment initiation ID.",
      "method": "POST",
      "endpoint": "/tools/execute",
      "auth": {
        "required": true,
        "header": "Authorization",
        "accepted_formats": [
          "sbp_live_xxx",
          "Bearer sbp_live_xxx"
        ]
      },
      "response_contract": "StandardResponse<T> with success, data, metadata, insights, summary",
      "output_schema": {
        "type": "object",
        "required": [
          "success",
          "timestamp",
          "data",
          "metadata",
          "insights",
          "summary"
        ],
        "additionalProperties": true,
        "properties": {
          "success": {
            "type": "boolean"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "data": {
            "type": "object"
          },
          "metadata": {
            "type": "object"
          },
          "insights": {
            "type": "object"
          },
          "summary": {
            "type": "string"
          },
          "raw": {}
        },
        "notes": "Set include_raw=true to include optional raw upstream response payload."
      },
      "error_schema": {
        "type": "object",
        "required": [
          "error",
          "message"
        ],
        "additionalProperties": true,
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "request_id": {
            "type": "string"
          },
          "retryable": {
            "type": "boolean"
          }
        }
      },
      "error_model": {
        "domain_errors": [
          {
            "code": "RESOURCE_NOT_FOUND",
            "retryable": false,
            "suggested_next_tool": "initiate_payment"
          },
          {
            "code": "INVALID_REQUEST",
            "retryable": false,
            "suggested_next_tool": null
          }
        ]
      },
      "openapi_operation": {
        "method": "get",
        "path": "/api/public/payment_initiation"
      },
      "output_openapi_schema_ref": "#/components/schemas/SuccessPaymentInitiationResponse",
      "required_arguments": [
        "payment_initiation_id"
      ],
      "optional_arguments": [
        "enrich",
        "include_raw"
      ],
      "argument_hints": {
        "payment_initiation_id": "String ID returned by initiate_payment, e.g. 2724PI20250101010101001"
      },
      "argument_schema": {
        "payment_initiation_id": {
          "type": "string",
          "pattern": "^[0-9]+PI[0-9]+$"
        },
        "enrich": {
          "type": "boolean",
          "default": true
        },
        "include_raw": {
          "type": "boolean",
          "default": false
        }
      },
      "example": {
        "tool": "get_payment_initiation",
        "arguments": {
          "payment_initiation_id": "2724PI20250101010101001"
        }
      },
      "decision_guidance": {
        "when_to_use": "Use when you need the latest status of an initiated payment.",
        "preconditions": [
          "Valid payment_initiation_id"
        ],
        "retryable_errors": [
          "AUTH_MISSING_OR_INVALID"
        ],
        "non_retryable_errors": [
          "RESOURCE_NOT_FOUND",
          "INVALID_REQUEST"
        ],
        "next_best_tool_on_failure": "initiate_payment"
      },
      "retry_policy": {
        "safe_to_retry": true,
        "retry_on_status": [
          401,
          429,
          500
        ],
        "backoff": "exponential_jitter"
      },
      "idempotency_notes": "Read-only operation; safe to repeat with same input.",
      "error_contract": [
        {
          "status": 400,
          "code": "INVALID_REQUEST",
          "when": "Missing required field"
        },
        {
          "status": 401,
          "code": "AUTH_MISSING_OR_INVALID",
          "when": "Session/API key missing or invalid"
        },
        {
          "status": 404,
          "code": "RESOURCE_NOT_FOUND",
          "when": "Initiation ID not found"
        }
      ]
    },
    {
      "name": "initiate_direct_debit",
      "description": "Initiate a direct debit payment with account details and consent.",
      "method": "POST",
      "endpoint": "/tools/execute",
      "auth": {
        "required": true,
        "header": "Authorization",
        "accepted_formats": [
          "sbp_live_xxx",
          "Bearer sbp_live_xxx"
        ]
      },
      "response_contract": "StandardResponse<T> with success, data, metadata, insights, summary",
      "output_schema": {
        "type": "object",
        "required": [
          "success",
          "timestamp",
          "data",
          "metadata",
          "insights",
          "summary"
        ],
        "additionalProperties": true,
        "properties": {
          "success": {
            "type": "boolean"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "data": {
            "type": "object"
          },
          "metadata": {
            "type": "object"
          },
          "insights": {
            "type": "object"
          },
          "summary": {
            "type": "string"
          },
          "raw": {}
        },
        "notes": "Set include_raw=true to include optional raw upstream response payload."
      },
      "error_schema": {
        "type": "object",
        "required": [
          "error",
          "message"
        ],
        "additionalProperties": true,
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "request_id": {
            "type": "string"
          },
          "retryable": {
            "type": "boolean"
          }
        }
      },
      "error_model": {
        "transport_errors": [
          {
            "status": 400,
            "code": "INVALID_REQUEST",
            "retryable": false
          },
          {
            "status": 401,
            "code": "AUTH_MISSING_OR_INVALID",
            "retryable": true
          },
          {
            "status": 403,
            "code": "TOOL_NOT_PERMITTED",
            "retryable": false
          },
          {
            "status": 404,
            "code": "RESOURCE_NOT_FOUND",
            "retryable": false
          },
          {
            "status": 429,
            "code": "RATE_LIMITED",
            "retryable": true
          },
          {
            "status": 500,
            "code": "INTERNAL_ERROR",
            "retryable": true
          }
        ],
        "domain_error_shape": "Domain-level failures may also be represented in StandardResponse as success=false with summary/raw.error_code."
      },
      "openapi_operation": {
        "method": "post",
        "path": "/api/public/payment_initiation/direct_debit"
      },
      "output_openapi_schema_ref": "#/components/schemas/SuccessPaymentInitiationResponse",
      "required_arguments": [
        "name",
        "amount",
        "consent_received",
        "bsb",
        "account_number"
      ],
      "optional_arguments": [
        "phone_number",
        "notes",
        "destination",
        "include_raw"
      ],
      "argument_hints": {
        "consent_received": "Must be true / \"true\"."
      },
      "argument_schema": {
        "name": {
          "type": "string"
        },
        "amount": {
          "oneOf": [
            {
              "type": "number",
              "exclusiveMinimum": 0
            },
            {
              "type": "string",
              "pattern": "^\\d+(\\.\\d{1,2})?$"
            }
          ]
        },
        "consent_received": {
          "oneOf": [
            {
              "type": "boolean"
            },
            {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            }
          ]
        },
        "bsb": {
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "number"
            }
          ]
        },
        "account_number": {
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "number"
            }
          ]
        }
      },
      "example": {
        "tool": "initiate_direct_debit",
        "arguments": {
          "name": "John Citizen",
          "amount": "10.00",
          "consent_received": true,
          "bsb": "062000",
          "account_number": "12345678"
        }
      },
      "decision_guidance": {
        "when_to_use": "Use to create a direct debit payment initiation from account details.",
        "preconditions": [
          "name, amount, consent_received, bsb, account_number"
        ],
        "retryable_errors": [
          "AUTH_MISSING_OR_INVALID"
        ],
        "non_retryable_errors": [
          "INVALID_REQUEST",
          "BUSINESS_RULE_FAILURE"
        ],
        "next_best_tool_on_failure": "get_payment_initiation"
      },
      "idempotency_notes": "Creates a new payment initiation and is non-idempotent without caller deduplication.",
      "error_contract": [
        {
          "status": 400,
          "code": "INVALID_REQUEST",
          "when": "Malformed direct_debit payload or missing required fields"
        },
        {
          "status": 401,
          "code": "AUTH_MISSING_OR_INVALID",
          "when": "Session/API key missing or invalid"
        },
        {
          "status": 422,
          "code": "BUSINESS_RULE_FAILURE",
          "when": "Consent/amount/cooldown or provider validation failed"
        }
      ]
    },
    {
      "name": "update_bilateral_agreement",
      "description": "Update bilateral parameters for a payment agreement.",
      "method": "POST",
      "endpoint": "/tools/execute",
      "auth": {
        "required": true,
        "header": "Authorization",
        "accepted_formats": [
          "sbp_live_xxx",
          "Bearer sbp_live_xxx"
        ]
      },
      "response_contract": "StandardResponse<T> with success, data, metadata, insights, summary",
      "output_schema": {
        "type": "object",
        "required": [
          "success",
          "timestamp",
          "data",
          "metadata",
          "insights",
          "summary"
        ],
        "additionalProperties": true,
        "properties": {
          "success": {
            "type": "boolean"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "data": {
            "type": "object"
          },
          "metadata": {
            "type": "object"
          },
          "insights": {
            "type": "object"
          },
          "summary": {
            "type": "string"
          },
          "raw": {}
        },
        "notes": "Set include_raw=true to include optional raw upstream response payload."
      },
      "error_schema": {
        "type": "object",
        "required": [
          "error",
          "message"
        ],
        "additionalProperties": true,
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "request_id": {
            "type": "string"
          },
          "retryable": {
            "type": "boolean"
          }
        }
      },
      "error_model": {
        "transport_errors": [
          {
            "status": 400,
            "code": "INVALID_REQUEST",
            "retryable": false
          },
          {
            "status": 401,
            "code": "AUTH_MISSING_OR_INVALID",
            "retryable": true
          },
          {
            "status": 403,
            "code": "TOOL_NOT_PERMITTED",
            "retryable": false
          },
          {
            "status": 404,
            "code": "RESOURCE_NOT_FOUND",
            "retryable": false
          },
          {
            "status": 429,
            "code": "RATE_LIMITED",
            "retryable": true
          },
          {
            "status": 500,
            "code": "INTERNAL_ERROR",
            "retryable": true
          }
        ],
        "domain_error_shape": "Domain-level failures may also be represented in StandardResponse as success=false with summary/raw.error_code."
      },
      "openapi_operation": {
        "method": "patch",
        "path": "/api/public/payment_agreement/bilateral"
      },
      "output_openapi_schema_ref": "#/components/schemas/SuccessPaymentAgreementResponse",
      "required_arguments": [
        "maximum_amount",
        "frequency",
        "number_of_transactions_permitted"
      ],
      "optional_arguments": [
        "id",
        "phone_number",
        "agreement_type",
        "include_raw"
      ],
      "argument_hints": {
        "frequency": "Use supported stored codes like ADHO, DAIL, FRTN, INDA, MIAN, MNTH, QURT, WEEK, YEAR."
      },
      "argument_schema": {
        "id": {
          "type": "string"
        },
        "phone_number": {
          "type": "string"
        },
        "maximum_amount": {
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "number"
            }
          ]
        },
        "frequency": {
          "type": "string"
        },
        "number_of_transactions_permitted": {
          "type": "integer",
          "minimum": 1
        }
      },
      "example": {
        "tool": "update_bilateral_agreement",
        "arguments": {
          "id": "2882PA20251227045450257",
          "maximum_amount": "100.00",
          "frequency": "MNTH",
          "number_of_transactions_permitted": 2
        }
      },
      "decision_guidance": {
        "when_to_use": "Use to amend bilateral parameters on an existing payment agreement.",
        "preconditions": [
          "id or phone_number, maximum_amount, frequency, number_of_transactions_permitted"
        ],
        "retryable_errors": [
          "AUTH_MISSING_OR_INVALID"
        ],
        "non_retryable_errors": [
          "RESOURCE_NOT_FOUND",
          "VALIDATION_OR_BUSINESS_RULE"
        ],
        "next_best_tool_on_failure": "get_payment_agreement"
      },
      "idempotency_notes": "Updates agreement settings and is non-idempotent under concurrent updates.",
      "error_contract": [
        {
          "status": 400,
          "code": "INVALID_REQUEST",
          "when": "Malformed bilateral amend payload"
        },
        {
          "status": 401,
          "code": "AUTH_MISSING_OR_INVALID",
          "when": "Session/API key missing or invalid"
        },
        {
          "status": 404,
          "code": "RESOURCE_NOT_FOUND",
          "when": "Payment agreement not found"
        },
        {
          "status": 422,
          "code": "VALIDATION_OR_BUSINESS_RULE",
          "when": "Amount/rule validation failed"
        }
      ]
    },
    {
      "name": "generate_invoice",
      "description": "Generate checkout URL for invoice flow.",
      "method": "POST",
      "endpoint": "/tools/execute",
      "auth": {
        "required": true,
        "header": "Authorization",
        "accepted_formats": [
          "sbp_live_xxx",
          "Bearer sbp_live_xxx"
        ]
      },
      "response_contract": "StandardResponse<T> with success, data, metadata, insights, summary",
      "output_schema": {
        "type": "object",
        "required": [
          "success",
          "timestamp",
          "data",
          "metadata",
          "insights",
          "summary"
        ],
        "additionalProperties": true,
        "properties": {
          "success": {
            "type": "boolean"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "data": {
            "type": "object"
          },
          "metadata": {
            "type": "object"
          },
          "insights": {
            "type": "object"
          },
          "summary": {
            "type": "string"
          },
          "raw": {}
        },
        "notes": "Set include_raw=true to include optional raw upstream response payload."
      },
      "error_schema": {
        "type": "object",
        "required": [
          "error",
          "message"
        ],
        "additionalProperties": true,
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "request_id": {
            "type": "string"
          },
          "retryable": {
            "type": "boolean"
          }
        }
      },
      "error_model": {
        "transport_errors": [
          {
            "status": 400,
            "code": "INVALID_REQUEST",
            "retryable": false
          },
          {
            "status": 401,
            "code": "AUTH_MISSING_OR_INVALID",
            "retryable": true
          },
          {
            "status": 403,
            "code": "TOOL_NOT_PERMITTED",
            "retryable": false
          },
          {
            "status": 404,
            "code": "RESOURCE_NOT_FOUND",
            "retryable": false
          },
          {
            "status": 429,
            "code": "RATE_LIMITED",
            "retryable": true
          },
          {
            "status": 500,
            "code": "INTERNAL_ERROR",
            "retryable": true
          }
        ],
        "domain_error_shape": "Domain-level failures may also be represented in StandardResponse as success=false with summary/raw.error_code."
      },
      "openapi_operation": {
        "method": "post",
        "path": "/api/public/generate_invoice"
      },
      "output_openapi_schema_ref": "inline: { message, data: { checkout_url } }",
      "required_arguments": [
        "invoice"
      ],
      "optional_arguments": [
        "phone_number",
        "include_raw",
        "invoice.description",
        "invoice.bill_to",
        "invoice.address",
        "invoice.receiver_abn",
        "invoice.ref_no",
        "invoice.gst_included",
        "invoice.gst_does_not_apply",
        "invoice.email"
      ],
      "argument_hints": {
        "invoice.amount": "Invoice amount (AUD); max 1000"
      },
      "example": {
        "tool": "generate_invoice",
        "arguments": {
          "invoice": {
            "amount": "50.00",
            "gst_included": true
          }
        }
      },
      "decision_guidance": {
        "when_to_use": "Use to generate invoice checkout URL for external collection flow.",
        "preconditions": [
          "invoice payload"
        ],
        "retryable_errors": [
          "AUTH_MISSING_OR_INVALID"
        ],
        "non_retryable_errors": [
          "INVALID_REQUEST",
          "VALIDATION_OR_BUSINESS_RULE"
        ],
        "next_best_tool_on_failure": null
      },
      "idempotency_notes": "Creates a new invoice checkout URL/session per call; treat as non-idempotent.",
      "error_contract": [
        {
          "status": 400,
          "code": "INVALID_REQUEST",
          "when": "Invalid invoice payload shape"
        },
        {
          "status": 401,
          "code": "AUTH_MISSING_OR_INVALID",
          "when": "Session/API key missing or invalid"
        },
        {
          "status": 422,
          "code": "VALIDATION_OR_BUSINESS_RULE",
          "when": "Invoice validation/business rule failure"
        }
      ]
    },
    {
      "name": "get_auth_token",
      "description": "Exchange an API key for a backend bearer token (debug/non-production helper).",
      "method": "POST",
      "endpoint": "/tools/execute",
      "auth": {
        "required": true,
        "header": "Authorization",
        "accepted_formats": [
          "sbp_live_xxx",
          "Bearer sbp_live_xxx"
        ]
      },
      "response_contract": "StandardResponse<T> with success, data, metadata, insights, summary",
      "output_schema": {
        "type": "object",
        "required": [
          "success",
          "timestamp",
          "data",
          "metadata",
          "insights",
          "summary"
        ],
        "additionalProperties": true,
        "properties": {
          "success": {
            "type": "boolean"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "data": {
            "type": "object"
          },
          "metadata": {
            "type": "object"
          },
          "insights": {
            "type": "object"
          },
          "summary": {
            "type": "string"
          },
          "raw": {}
        },
        "notes": "Set include_raw=true to include optional raw upstream response payload."
      },
      "error_schema": {
        "type": "object",
        "required": [
          "error",
          "message"
        ],
        "additionalProperties": true,
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "request_id": {
            "type": "string"
          },
          "retryable": {
            "type": "boolean"
          }
        }
      },
      "error_model": {
        "domain_errors": [
          {
            "code": "TOOL_NOT_PERMITTED_IN_PRODUCTION",
            "retryable": false,
            "suggested_next_tool": "create_payment_agreement"
          }
        ]
      },
      "openapi_operation": {
        "method": "post",
        "path": "/api/public/authorization"
      },
      "output_openapi_schema_ref": "#/components/schemas/SuccessAuthorizationResponse",
      "required_arguments": [],
      "optional_arguments": [
        "include_token_in_response"
      ],
      "argument_hints": {
        "include_token_in_response": "Boolean, defaults false. Keep false for normal agent usage."
      },
      "argument_schema": {
        "include_token_in_response": {
          "type": "boolean",
          "default": false
        }
      },
      "auth_note": "Uses MCP session auth (OAuth/Authorization header) by default. Stdio clients may provide authorization in tool args when needed.",
      "example": {
        "tool": "get_auth_token",
        "arguments": {
          "include_token_in_response": false
        }
      },
      "decision_guidance": {
        "when_to_use": "Use only for non-production debugging of auth flow.",
        "preconditions": [
          "Non-production environment"
        ],
        "retryable_errors": [
          "AUTH_MISSING_OR_INVALID"
        ],
        "non_retryable_errors": [
          "TOOL_NOT_PERMITTED_IN_PRODUCTION"
        ],
        "next_best_tool_on_failure": "create_payment_agreement"
      },
      "retry_policy": {
        "safe_to_retry": true,
        "retry_on_status": [
          401,
          429,
          500
        ],
        "backoff": "exponential_jitter"
      },
      "idempotency_notes": "Returns current auth state; safe to repeat in non-production.",
      "error_contract": [
        {
          "status": 401,
          "code": "AUTH_MISSING_OR_INVALID",
          "when": "Session/API key missing or invalid"
        },
        {
          "status": 403,
          "code": "TOOL_NOT_PERMITTED_IN_PRODUCTION",
          "when": "Tool disabled in production"
        }
      ]
    }
  ],
  "metadata": {
    "discovery_schema_version": "2026-04-15",
    "compatibility": {
      "policy": "backward-compatible additive fields only for discovery metadata",
      "deprecation_window_days": 90
    },
    "official_openapi": {
      "mcp": "https://raw.githubusercontent.com/shabaaspay/shabaas-ai/main/openapi/openapi.yaml",
      "repository": "https://github.com/shabaaspay/shabaas-ai"
    },
    "auth_behavior": {
      "entry_header": "Authorization",
      "accepted_formats": [
        "sbp_live_xxx",
        "Bearer sbp_live_xxx"
      ],
      "token_cache_ttl_ms": 3000000,
      "cache_scope": "per_api_key",
      "upstream_token_exchange": true
    },
    "error_taxonomy": {
      "canonical_error_codes": [
        "AUTH_MISSING_OR_INVALID",
        "TOOL_NOT_PERMITTED",
        "TOOL_NOT_PERMITTED_IN_PRODUCTION",
        "INVALID_REQUEST",
        "INVALID_AMOUNT_OR_REQUEST",
        "RESOURCE_NOT_FOUND",
        "AGREEMENT_NOT_FOUND",
        "DEVELOPER_CREDITS_EXHAUSTED",
        "VALIDATION_OR_BUSINESS_RULE",
        "BUSINESS_RULE_FAILURE"
      ],
      "transport_errors": [
        {
          "status": 400,
          "reason": "Invalid JSON or missing tool name"
        },
        {
          "status": 401,
          "reason": "Missing/invalid API key in Authorization header"
        },
        {
          "status": 403,
          "reason": "Tool blocked by client policy"
        },
        {
          "status": 404,
          "reason": "Unknown tool name"
        },
        {
          "status": 429,
          "reason": "Rate limit exceeded"
        },
        {
          "status": 500,
          "reason": "Unhandled server error"
        }
      ],
      "domain_error_codes_reference": "https://raw.githubusercontent.com/shabaaspay/shabaas-ai/main/openapi/openapi.yaml",
      "note": "Domain-level failures are returned in StandardResponse summary/raw fields and may include upstream error_code values from ShaBaas APIs."
    }
  },
  "direct_api_access": {
    "description": "You can also call ShaBaas API directly through this proxy",
    "base_url": "/api",
    "example": "POST /api/public/authorization"
  }
}