@payware/mcp-server 1.3.3 → 1.5.0

package/src/merchant/products/list-products.js

@@ -1,11 +1,13 @@
 import { getProducts } from '../../shared/products/products-api.js';
 import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { READS } from '../../shared/tool-annotations.js';
 
 /**
  * List products tool implementation for merchants
  */
 export const listProductsTool = {
   name: "payware_products_list_products",
+  annotations: READS,
   description: "Get a list of all products for the merchant account",
 
   inputSchema: {
@@ -18,8 +20,7 @@ export const listProductsTool = {
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for authentication (uses environment-specific private key as default)",
-        default: getPrivateKeySafe()
+        description: "RSA private key for authentication (uses environment-specific private key as default)"
       },
       useSandbox: {
         type: "boolean",

package/src/merchant/products/schedules.js

@@ -7,12 +7,14 @@ import {
 } from '../../shared/products/products-api.js';
 import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
 import { PRICE_CORRECTION_TYPES, CORRECTION_TYPES } from '../../shared/products/products-api.js';
+import { CHANGES, CREATES, READS } from '../../shared/tool-annotations.js';
 
 /**
  * Create price schedule tool implementation for merchants
  */
 export const createScheduleTool = {
   name: "payware_products_create_schedule",
+  annotations: CREATES,
   description: "Create a price schedule for a product to manage time-based pricing",
 
   inputSchema: {
@@ -62,8 +64,7 @@ export const createScheduleTool = {
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for authentication (uses environment-specific private key as default)",
-        default: getPrivateKeySafe()
+        description: "RSA private key for authentication (uses environment-specific private key as default)"
       },
       useSandbox: {
         type: "boolean",
@@ -174,6 +175,7 @@ ${JSON.stringify(schedule, null, 2)}
  */
 export const getSchedulesTool = {
   name: "payware_products_get_schedules",
+  annotations: READS,
   description: "Get all price schedules for a product",
 
   inputSchema: {
@@ -191,8 +193,7 @@ export const getSchedulesTool = {
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for authentication (uses environment-specific private key as default)",
-        default: getPrivateKeySafe()
+        description: "RSA private key for authentication (uses environment-specific private key as default)"
       },
       useSandbox: {
         type: "boolean",
@@ -286,6 +287,7 @@ ${schedulesList}
  */
 export const getScheduleTool = {
   name: "payware_products_get_schedule",
+  annotations: READS,
   description: "Get detailed information about a specific price schedule",
 
   inputSchema: {
@@ -307,8 +309,7 @@ export const getScheduleTool = {
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for authentication (uses environment-specific private key as default)",
-        default: getPrivateKeySafe()
+        description: "RSA private key for authentication (uses environment-specific private key as default)"
       },
       useSandbox: {
         type: "boolean",
@@ -399,6 +400,7 @@ ${JSON.stringify(schedule, null, 2)}
  */
 export const updateScheduleTool = {
   name: "payware_products_update_schedule",
+  annotations: CHANGES,
   description: "Update an existing price schedule. Only provide fields you want to change.",
 
   inputSchema: {
@@ -449,8 +451,7 @@ export const updateScheduleTool = {
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for authentication (uses environment-specific private key as default)",
-        default: getPrivateKeySafe()
+        description: "RSA private key for authentication (uses environment-specific private key as default)"
       },
       useSandbox: {
         type: "boolean",
@@ -547,6 +548,7 @@ ${JSON.stringify(schedule, null, 2)}
  */
 export const deleteScheduleTool = {
   name: "payware_products_delete_schedule",
+  annotations: CHANGES,
   description: "Delete a price schedule. This action cannot be undone.",
 
   inputSchema: {
@@ -568,8 +570,7 @@ export const deleteScheduleTool = {
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for authentication (uses environment-specific private key as default)",
-        default: getPrivateKeySafe()
+        description: "RSA private key for authentication (uses environment-specific private key as default)"
       },
       useSandbox: {
         type: "boolean",

package/src/merchant/products/update-product.js

@@ -1,12 +1,14 @@
 import { updateProduct } from '../../shared/products/products-api.js';
 import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
 import { PRODUCT_TYPES, OVERLAP_PRIORITY } from '../../shared/products/products-api.js';
+import { CHANGES } from '../../shared/tool-annotations.js';
 
 /**
  * Update product tool implementation for merchants
  */
 export const updateProductTool = {
   name: "payware_products_update_product",
+  annotations: CHANGES,
   description: `Update an existing product. Only provide the fields you want to change.
 
 **Product Structure:**
@@ -128,8 +130,7 @@ export const updateProductTool = {
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for authentication (uses environment-specific private key as default)",
-        default: getPrivateKeySafe()
+        description: "RSA private key for authentication (uses environment-specific private key as default)"
       },
       useSandbox: {
         type: "boolean",

package/src/merchant/transactions/cancel-transaction.js

@@ -3,6 +3,7 @@ import { createJWTToken } from '../../core/auth/jwt-token.js';
 import { createMinimizedJSON } from '../../core/utils/json-serializer.js';
 import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
 import { apiErrorResult } from '../../shared/api-errors.js';
+import { CHANGES } from '../../shared/tool-annotations.js';
 
 /**
  * Cancel a transaction via payware API
@@ -76,6 +77,7 @@ export async function cancelTransaction({
  */
 export const cancelTransactionTool = {
   name: "payware_operations_cancel_transaction",
+  annotations: CHANGES,
   description: "Cancel an ACTIVE transaction created by this merchant. Only the merchant who created the transaction can cancel it, and only before it has been processed.",
   inputSchema: {
     type: "object",
@@ -104,8 +106,7 @@ export const cancelTransactionTool = {
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for JWT token creation. Can use PAYWARE_PRIVATE_KEY_PATH env var as default.",
-        default: getPrivateKeySafe()
+        description: "RSA private key for JWT token creation. Can use PAYWARE_PRIVATE_KEY_PATH env var as default."
       },
       useSandbox: {
         type: "boolean",
@@ -213,7 +214,7 @@ ${JSON.stringify(result.error.details || result.error, null, 2)}
 **Timestamp:** ${result.timestamp}
 
 **Common Issues:**
-1. **ERR_MISSING_TRANSACTION**: Transaction not found or expired
+1. **ERR_MISSING_TRANSACTION**: Transaction not found. **ERR_TRANSACTION_EXPIRED** (also 404): its time to live has run out and it is already closed as unpaid
 2. **ERR_ALREADY_PROCESSED**: Transaction already processed, cannot cancel
 3. **ERR_UNAUTHORIZED_OPERATION**: Only transaction creator can cancel
 4. **ERR_INVALID_STATUS_MESSAGE**: Status message invalid or too long

package/src/merchant/transactions/create-transaction.js

@@ -2,6 +2,7 @@ import axios from 'axios';
 import { createJWTToken } from '../../core/auth/jwt-token.js';
 import { createMinimizedJSON } from '../../core/utils/json-serializer.js';
 import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { CREATES } from '../../shared/tool-annotations.js';
 
 /**
  * Create a transaction via payware API
@@ -39,6 +40,7 @@ export async function createTransaction({
   barBarHeight,
   barFontSize,
   barHumanReadableLocation,
+  idempotencyKey,
   useSandbox = true
 }) {
   if (!reasonL1) {
@@ -141,7 +143,8 @@ export async function createTransaction({
   const headers = {
     'Authorization': `Bearer ${tokenData.token}`,
     'Content-Type': 'application/json',
-    'Api-Version': '1' // Required: current API version
+    'Api-Version': '1', // Required: current API version
+    ...(idempotencyKey && { 'Idempotency-Key': idempotencyKey })
   };
   
   try {
@@ -159,6 +162,7 @@ export async function createTransaction({
       success: true,
       transaction: response.data,
       requestId: response.headers['x-request-id'],
+      replayed: response.headers?.['idempotent-replayed'] === 'true',
       timestamp: new Date().toISOString()
     };
   } catch (error) {
@@ -196,6 +200,7 @@ Original error: ${enhancedMessage}`;
  */
 export const createTransactionTool = {
   name: "payware_operations_create_transaction",
+  annotations: CREATES,
   description: `Create a new payware transaction. Parameters map to the following API structure:
 
 📋 **ROOT LEVEL** (Transaction metadata):
@@ -267,6 +272,11 @@ ISV's software is running on that producer's hardware.`,
   inputSchema: {
     type: "object",
     properties: {
+      idempotencyKey: {
+        type: "string",
+        description: "Optional. Sent as the Idempotency-Key header. Use one value per payment (a UUID is typical) and the same value on every retry of it: a retry with the same key and body within 24 hours returns the transaction the first call created instead of a new one, and the result reports replayed: true. The same key with a different body is refused (422 ERR_IDEMPOTENCY_KEY_REUSED); a retry while the first call still runs gets 409 ERR_IDEMPOTENCY_KEY_IN_PROGRESS.",
+        pattern: "^[\\x21-\\x7E]{1,255}$"
+      },
       type: {
         type: "string",
         enum: ["PLAIN", "QR", "BARCODE"],
@@ -444,6 +454,7 @@ ISV's software is running on that producer's hardware.`,
       barBarHeight,
       barFontSize,
       barHumanReadableLocation,
+      idempotencyKey,
       useSandbox = true
     } = args;
     
@@ -488,6 +499,7 @@ ISV's software is running on that producer's hardware.`,
       barBarHeight,
       barFontSize,
       barHumanReadableLocation,
+      idempotencyKey,
       useSandbox
     });
     
@@ -524,7 +536,7 @@ ${JSON.stringify(result.transaction, null, 2)}
 
 **Next Steps:**
 1. Save the transaction ID: \`${result.transaction.transactionId || 'N/A'}\`
-2. Use \`payware_transactions_get_transaction_status\` to check status
+2. Use \`payware_operations_get_transaction_status\` to check status
 3. Wait for callback notification (if callback URL provided)
 4. Process payment through payware interface`
         }]

package/src/merchant/transactions/get-status.js

@@ -2,6 +2,7 @@ import axios from 'axios';
 import { createJWTToken } from '../../core/auth/jwt-token.js';
 import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
 import { apiErrorResult } from '../../shared/api-errors.js';
+import { READS } from '../../shared/tool-annotations.js';
 
 /**
  * Get transaction status from payware API
@@ -67,11 +68,12 @@ function formatTransactionStatus(transaction) {
  */
 export const getTransactionStatusTool = {
   name: "payware_operations_get_transaction_status", 
+  annotations: READS,
   description: `Get status of an ACTIVE transaction by ID (for completed/expired transactions use transaction history tool).
 
 **Endpoint:** GET /transactions/{transactionId}
 **Use Case:** Check status of ACTIVE transactions only. This endpoint only returns transactions with ACTIVE status.
-**Note:** For transactions with final statuses (CONFIRMED, DECLINED, FAILED, EXPIRED, CANCELLED), use 'payware_transactions_get_history' instead.
+**Note:** For transactions with final statuses (CONFIRMED, DECLINED, FAILED, EXPIRED, CANCELLED), use 'payware_operations_get_transaction_history' instead.
 
 🛍️ **Product-originated transactions carry a nested \`product\` object.** Since 2026-07-22 the
 presentation fields are grouped under \`product\` rather than sitting flat on the response - the old
@@ -123,8 +125,7 @@ with ERR_FEE_MISMATCH. Echo \`fee\` back unchanged instead.`,
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for JWT token creation. Can use PAYWARE_PRIVATE_KEY_PATH env var as default.",
-        default: getPrivateKeySafe()
+        description: "RSA private key for JWT token creation. Can use PAYWARE_PRIVATE_KEY_PATH env var as default."
       },
       useSandbox: {
         type: "boolean",

package/src/merchant/transactions/process-transaction.js

@@ -3,6 +3,7 @@ import { createJWTToken } from '../../core/auth/jwt-token.js';
 import { createMinimizedJSON } from '../../core/utils/json-serializer.js';
 import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
 import { apiErrorResult } from '../../shared/api-errors.js';
+import { COMMITS } from '../../shared/tool-annotations.js';
 
 /**
  * Process a transaction via payware API (for merchants accepting payments)
@@ -24,6 +25,7 @@ export async function processTransaction({
   paymentMethod,
   partnerId,
   privateKey,
+  idempotencyKey,
   useSandbox = true
 }) {
   if (!transactionId) {
@@ -79,7 +81,8 @@ export async function processTransaction({
   const headers = {
     'Authorization': `Bearer ${tokenData.token}`,
     'Content-Type': 'application/json',
-    'Api-Version': '1'  // Required: current API version
+    'Api-Version': '1', // Required: current API version
+    ...(idempotencyKey && { 'Idempotency-Key': idempotencyKey })
   };
 
   try {
@@ -95,6 +98,7 @@ export async function processTransaction({
       success: true,
       transaction: response.data,
       requestId: response.headers['x-request-id'],
+      replayed: response.headers?.['idempotent-replayed'] === 'true',
       timestamp: new Date().toISOString()
     };
   } catch (error) {
@@ -107,6 +111,7 @@ export async function processTransaction({
  */
 export const processTransactionTool = {
   name: "payware_operations_process_transaction",
+  annotations: COMMITS,
   description: `Process a PEER transaction (for merchants accepting payments by scanning customer QR/barcode).
 
 **Use Case:** Merchant scans customer's payware QR code or barcode to accept payment.
@@ -136,10 +141,15 @@ export const processTransactionTool = {
     type: "object",
     additionalProperties: false,
     properties: {
+      idempotencyKey: {
+        type: "string",
+        description: "Optional. Sent as the Idempotency-Key header. Use one value per payment (a UUID is typical) and the same value on every retry of it: a retry with the same key and body within 24 hours returns the transaction the first call created instead of a new one, and the result reports replayed: true. The same key with a different body is refused (422 ERR_IDEMPOTENCY_KEY_REUSED); a retry while the first call still runs gets 409 ERR_IDEMPOTENCY_KEY_IN_PROGRESS.",
+        pattern: "^[\\x21-\\x7E]{1,255}$"
+      },
       transactionId: {
         type: "string",
-        description: "Transaction ID to process. Format: 2-char prefix + 8-char ID. Supports: 'pw' (standard), 'pr' (product), 'ps' (soundbite)",
-        pattern: "^(pw|pr|ps)[0-9A-Za-z]{8}$"
+        description: "Transaction ID to process. Format: 2-char prefix + 8-char ID. Supports: 'pw' (standard), 'pr' (product), 'pl' (placement: pays as its product, and the payment is attributed to the placement), 'ps' (soundbite)",
+        pattern: "^(pw|pr|pl|ps)[0-9A-Za-z]{8}$"
       },
       amount: {
         type: ["number", "string"], 
@@ -207,8 +217,7 @@ export const processTransactionTool = {
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for JWT token creation. Can use PAYWARE_PRIVATE_KEY_PATH env var as default.",
-        default: getPrivateKeySafe()
+        description: "RSA private key for JWT token creation. Can use PAYWARE_PRIVATE_KEY_PATH env var as default."
       },
       useSandbox: {
         type: "boolean",
@@ -235,6 +244,7 @@ export const processTransactionTool = {
       paymentMethod,
       partnerId = getPartnerIdSafe(),
       privateKey = getPrivateKeySafe(args.useSandbox ?? true),
+      idempotencyKey,
       useSandbox = true
     } = args;
     
@@ -273,6 +283,7 @@ export const processTransactionTool = {
       paymentMethod,
       partnerId,
       privateKey,
+      idempotencyKey,
       useSandbox
     });
     
@@ -333,7 +344,7 @@ ${JSON.stringify(result.error.details || result.error, null, 2)}
 **Timestamp:** ${result.timestamp}
 
 **Common Issues:**
-1. **ERR_MISSING_TRANSACTION**: Transaction ID not found or expired
+1. **ERR_MISSING_TRANSACTION**: Transaction ID not found. **ERR_TRANSACTION_EXPIRED** (also 404): its time to live has run out and it is closed as unpaid
 2. **ERR_UNKNOWN_ROLE**: Transaction generated by payee (can't process own transaction)
 3. **ERR_ALREADY_PROCESSED**: Transaction already processed
 4. **ERR_SPECIFYING_AMOUNT_NOT_ALLOWED**: Amount exceeds transaction limit

package/src/merchant/transactions/simulate-callback.js

@@ -9,6 +9,8 @@
  * @param {Object} options - Additional options
  * @returns {Object} Mock callback payload
  */
+import { LOCAL } from '../../shared/tool-annotations.js';
+
 export function generateMockCallback(transactionId, status = 'CONFIRMED', options = {}) {
   const {
     amount = '57.60',
@@ -137,6 +139,7 @@ export async function simulateCallbackDelivery(callbackUrl, payload) {
  */
 export const simulateCallbackTool = {
   name: "payware_operations_simulate_callback",
+  annotations: LOCAL,
   description: `Simulate callback scenarios for testing webhook handling.
 
 Generates the payload a merchant's \`callbackUrl\` actually receives, so a handler can be built and

package/src/merchant/transactions/transaction-history.js

@@ -2,6 +2,7 @@ import axios from 'axios';
 import { createJWTToken } from '../../core/auth/jwt-token.js';
 import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
 import { apiErrorResult } from '../../shared/api-errors.js';
+import { READS } from '../../shared/tool-annotations.js';
 
 /**
  * Get transaction history from payware API (for completed/expired transactions)
@@ -91,11 +92,12 @@ function formatTransactionHistory(transaction) {
  */
 export const getTransactionHistoryTool = {
   name: "payware_operations_get_transaction_history", 
+  annotations: READS,
   description: `Get history of completed/finalized transactions with final statuses.
 
 **Endpoint:** GET /transactions-history/{transactionId}
 **Use Case:** Retrieve transactions with final statuses: CONFIRMED, DECLINED, FAILED, EXPIRED, CANCELLED.
-**Note:** For ACTIVE transactions, use 'payware_transactions_get_transaction_status' instead.
+**Note:** For ACTIVE transactions, use 'payware_operations_get_transaction_status' instead.
 
 📦 **This is where the delivery address lives.** For a SHIPPABLE transaction, \`deliveryAddress\`
 (fullName, streetAddressLine1/2, zipCode, city, region, country, phoneNumber, email) is returned
@@ -129,8 +131,7 @@ retry once the window passes. The failure result exposes this as \`error.throttl
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for JWT token creation. Can use PAYWARE_PRIVATE_KEY_PATH env var as default.",
-        default: getPrivateKeySafe()
+        description: "RSA private key for JWT token creation. Can use PAYWARE_PRIVATE_KEY_PATH env var as default."
       },
       useSandbox: {
         type: "boolean",
@@ -262,7 +263,7 @@ ${JSON.stringify(result.error.details || result.error, null, 2)}
 1. Verify transaction ID is correct: 10 characters total, starts with 'pw' (standard), 'pr' (product), or 'ps' (soundbite)
 2. Ensure transaction exists and you have access to it
 3. If getting rate limit errors, wait 60 seconds before retrying
-4. For ACTIVE transactions, use 'payware_transactions_get_transaction_status' instead
+4. For ACTIVE transactions, use 'payware_operations_get_transaction_status' instead
 5. This endpoint only returns transactions with final statuses (CONFIRMED, DECLINED, FAILED, EXPIRED, CANCELLED)`;
 
       return {

package/src/payment-institution/data/index.js

@@ -19,10 +19,12 @@ import {
   LOCALES
 } from '../../shared/data/data-api.js';
 import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { CHANGES, CREATES, READS } from '../../shared/tool-annotations.js';
 
 // Create a payment institution tool factory
-const createPIDataTool = (toolName, apiFunction, description, additionalParams = {}) => ({
+const createPIDataTool = (toolName, apiFunction, description, additionalParams = {}, annotations) => ({
   name: `payware_data_${toolName}`,
+  annotations,
   description: `${description} (Payment Institution data access)`,
   inputSchema: {
     type: "object",
@@ -35,8 +37,7 @@ const createPIDataTool = (toolName, apiFunction, description, additionalParams =
       },
       privateKey: {
         type: "string",
-        description: "Payment Institution RSA private key for authentication. Uses environment-specific private key as default.",
-        default: getPrivateKeySafe()
+        description: "Payment Institution RSA private key for authentication. Uses environment-specific private key as default."
       },
       ...additionalParams
     },
@@ -78,6 +79,7 @@ const createPIDataTool = (toolName, apiFunction, description, additionalParams =
  */
 export const generateReportTool = {
   name: "payware_data_generate_report",
+  annotations: CREATES,
   description: "Generate an asynchronous data report for Payment Institution analysis. Focuses on P2P transaction flows and cross-institution payments. Production only.",
   inputSchema: {
     type: "object",
@@ -122,8 +124,7 @@ export const generateReportTool = {
       },
       privateKey: {
         type: "string",
-        description: "Payment Institution RSA private key for authentication. Uses environment-specific private key as default.",
-        default: getPrivateKeySafe()
+        description: "Payment Institution RSA private key for authentication. Uses environment-specific private key as default."
       }
     },
     required: ["reportUnitId"]
@@ -221,7 +222,7 @@ This feature is only available in the production environment, not in sandbox.
 };
 
 // Create all other PI data tools
-export const listReportsTool = createPIDataTool('list_reports', listReports, 'List All Available Reports', {});
+export const listReportsTool = createPIDataTool('list_reports', listReports, 'List All Available Reports', {}, READS);
 
 export const getReportRequestsTool = createPIDataTool('get_report_requests', getReportRequests, 'Get Report Request History', {
   reportId: {
@@ -229,21 +230,21 @@ export const getReportRequestsTool = createPIDataTool('get_report_requests', get
     description: "The report unit ID (path) to get execution history for (e.g., '/processedTransactions')",
     enum: Object.values(REPORT_TYPES)
   }
-});
+}, READS);
 
 export const getExportListTool = createPIDataTool('get_export_list', getExportList, 'Get Export List for Request', {
   requestId: {
     type: "string",
     description: "The request ID (UUID) to get exports for"
   }
-});
+}, READS);
 
 export const getReportStatusTool = createPIDataTool('get_report_status', getReportStatus, 'Get Report Status', {
   requestId: {
     type: "string",
     description: "The request ID returned from the report generation request (UUID format)"
   }
-});
+}, READS);
 
 export const exportReportTool = createPIDataTool('export_report', exportReport, 'Export Report', {
   requestId: {
@@ -256,35 +257,35 @@ export const exportReportTool = createPIDataTool('export_report', exportReport,
     enum: Object.values(EXPORT_FORMATS),
     default: EXPORT_FORMATS.PDF
   }
-});
+}, CREATES);
 
 export const getExportStatusTool = createPIDataTool('get_export_status', getExportStatus, 'Get Export Status', {
   exportId: {
     type: "string",
     description: "The export ID returned from the export request (UUID format)"
   }
-});
+}, READS);
 
 export const downloadExportTool = createPIDataTool('download_export', downloadExport, 'Download Export', {
   exportId: {
     type: "string",
     description: "The export ID from the export request (UUID format)"
   }
-});
+}, READS);
 
 export const cancelReportTool = createPIDataTool('cancel_report', cancelReport, 'Cancel Report', {
   requestId: {
     type: "string",
     description: "The request ID of the report to cancel (UUID format)"
   }
-});
+}, CHANGES);
 
 export const cancelExportTool = createPIDataTool('cancel_export', cancelExport, 'Cancel Export', {
   exportId: {
     type: "string",
     description: "The export ID of the export to cancel (UUID format)"
   }
-});
+}, CHANGES);
 
 /**
  * All Payment Institution data tools

package/src/payment-institution/deep-links/delete-transaction-link.js

@@ -1,11 +1,13 @@
 import { deleteTransactionDeepLink } from '../../shared/deep-links/api.js';
 import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { CHANGES } from '../../shared/tool-annotations.js';
 
 /**
  * Delete deep link for a payment institution transaction
  */
 export const deleteTransactionLinkTool = {
   name: "payware_deep_links_delete_transaction_link",
+  annotations: CHANGES,
   description: `Delete an active deep link for a transaction where the payment institution acts as source (SRC) or destination (DST). Once deleted, the deep link URL will no longer redirect to the payware mobile app.
 
 **Use Cases:**
@@ -34,8 +36,7 @@ export const deleteTransactionLinkTool = {
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for JWT token creation. Uses environment-specific private key as default.",
-        default: getPrivateKeySafe()
+        description: "RSA private key for JWT token creation. Uses environment-specific private key as default."
       }
     },
     required: ["transactionId"]

package/src/payment-institution/deep-links/get-transaction-link.js

@@ -1,16 +1,18 @@
 import { getTransactionDeepLink } from '../../shared/deep-links/api.js';
 import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { ADDS } from '../../shared/tool-annotations.js';
 
 /**
  * Get deep link for a payment institution transaction
  */
 export const getTransactionLinkTool = {
   name: "payware_deep_links_get_transaction_link",
+  annotations: ADDS,
   description: `Get an active deep link for a transaction where the payment institution acts as source (SRC) or destination (DST). Returns a clickable URL that redirects to the payware mobile app.
 
 **Deep Link Format:**
 - Web URL: https://go.payware.eu/{transactionId}
-- Mobile Redirect: payware://{transactionId}
+- Mobile Redirect: payware:/{transactionId} (one slash: the identifier is case-sensitive, so it must not sit in the URI host, which redirect services lowercase)
 
 **Use Cases:**
 - P2P payments initiated via messaging services
@@ -19,6 +21,7 @@ export const getTransactionLinkTool = {
 
 **Important Notes:**
 - Deep links are only supported in production environment
+- Apps that open payware links must accept \`payware:\` followed by one, two or three slashes (QR codes and NFC tags carry \`payware://{id}\`): read the identifier after the scheme and any slashes, up to \`/\`, \`?\` or \`#\`, and keep its case
 - Link expiration is synchronized with the referenced transaction
 - Payment institutions only manage transaction links (no product links)
 - Traditional deep links that route to app content when app is installed`,
@@ -38,8 +41,7 @@ export const getTransactionLinkTool = {
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for JWT token creation. Uses environment-specific private key as default.",
-        default: getPrivateKeySafe()
+        description: "RSA private key for JWT token creation. Uses environment-specific private key as default."
       }
     },
     required: ["transactionId"]
@@ -83,7 +85,7 @@ export const getTransactionLinkTool = {
 **Deep Link Details:**
 - Transaction ID: ${transactionId}
 - Web URL: ${linkUrl}
-- Mobile Redirect: payware://${transactionId}
+- Mobile Redirect: payware:/${transactionId}
 
 **Payment Institution Info:**
 - Partner ID: ${partnerId}
@@ -106,7 +108,7 @@ ${JSON.stringify(result.data, null, 2)}
 
 **Usage:**
 1. Share the web URL: \`${linkUrl}\`
-2. On mobile devices, it will redirect to: \`payware://${transactionId}\`
+2. On mobile devices, it will redirect to: \`payware:/${transactionId}\`
 3. Link expires when the transaction expires
 4. Use for P2P transaction notifications and sharing`
         }]
@@ -129,7 +131,7 @@ ${JSON.stringify(result.data, null, 2)}
 5. **Invalid transaction ID**: Ensure transaction ID format is correct
 
 **Troubleshooting:**
-1. Verify transaction exists using \`payware_transactions_get_transaction_status\`
+1. Verify transaction exists using \`payware_operations_get_transaction_status\`
 2. Check if running in production environment
 3. Ensure JWT authentication is working
 4. Confirm payment institution role in transaction