@payware/mcp-server 1.3.3 → 1.4.0

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",

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
@@ -196,6 +197,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):
@@ -524,7 +526,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)
@@ -107,6 +108,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.
@@ -138,8 +140,8 @@ export const processTransactionTool = {
     properties: {
       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 +209,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",

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

package/src/payment-institution/transactions/create-pi-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 { CREATES } from '../../shared/tool-annotations.js';
 
 /**
  * Create a payment institution transaction via payware API
@@ -150,6 +151,7 @@ export async function createPITransaction({
  */
 export const createPITransactionTool = {
   name: "payware_operations_create_transaction",
+  annotations: CREATES,
   description: `Create a new payware transaction as a payment institution. Payment institutions must specify their role and account details.
 
 **Payment Institution Features:**
@@ -245,8 +247,7 @@ export const createPITransactionTool = {
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for JWT token creation. Uses environment-specific private key as default.",
-        default: getPrivateKeySafe(true)
+        description: "RSA private key for JWT token creation. Uses environment-specific private key as default."
       },
       passbackParams: {
         type: "string",
@@ -437,7 +438,7 @@ ${JSON.stringify(result.transaction, null, 2)}
 **Next Steps:**
 1. Save the transaction ID: \`${result.transaction.transactionId || 'N/A'}\`
 2. ${role === 'SRC' ? 'Share transaction ID with payee for processing' : 'Wait for payer to process this transaction'}
-3. Use \`payware_pi_get_transaction_status\` to check status
+3. Use \`payware_operations_get_transaction_status\` to check status
 4. Monitor callback notifications (if callback URL provided)
 5. ${role === 'SRC' ? 'Complete payment through payware interface' : 'Handle incoming payment processing'}`
         }]

package/src/payment-institution/transactions/finalize-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';
 
 /**
  * Finalize a transaction as a payment institution via payware API
@@ -98,6 +99,7 @@ export async function finalizeTransaction({
  */
 export const finalizeTransactionTool = {
   name: "payware_operations_finalize_transaction",
+  annotations: COMMITS,
   description: `Finalize a transaction as a payment institution. This updates the transaction status after execution in your payment network.
 
 **Payment Institution Finalization:**
@@ -164,8 +166,7 @@ export const finalizeTransactionTool = {
       },
       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."
       },
       useSandbox: {
         type: "boolean",
@@ -233,6 +234,8 @@ export const finalizeTransactionTool = {
       privateKey,
       useSandbox
     });
+    // The success text quotes the endpoint. The helper above keeps its own baseUrl, so it needs one here.
+    const baseUrl = useSandbox ? getSandboxUrl() : getProductionUrl();
 
     if (result.success) {
       const statusEmojis = {
@@ -277,7 +280,7 @@ ${JSON.stringify(result.transaction, null, 2)}
 ${status === 'CONFIRMED' ?
   `1. ✅ Payment completed successfully
 2. Transaction funds should be processed in your network
-3. Use \`payware_pi_get_transaction_history\` to retrieve details later` :
+3. Use \`payware_operations_get_transaction_history\` to retrieve details later` :
   `1. ⚠️ Payment not completed due to: ${statusMessage || status}
 2. Transaction marked as ${status} in payware system
 3. All parties notified via callbacks`

package/src/payment-institution/transactions/get-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 via payware API (completed/expired transactions)
@@ -54,6 +55,7 @@ export async function getPITransactionHistory({
  */
 export const getPITransactionHistoryTool = {
   name: "payware_operations_get_transaction_history",
+  annotations: READS,
   description: `Get the complete history of a completed or expired payware transaction as a payment institution.
 
 **Use Cases:**
@@ -86,8 +88,7 @@ export const getPITransactionHistoryTool = {
       },
       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."
       },
       useSandbox: {
         type: "boolean",
@@ -124,6 +125,8 @@ export const getPITransactionHistoryTool = {
       privateKey,
       useSandbox
     });
+    // The success text quotes the endpoint. The helper above keeps its own baseUrl, so it needs one here.
+    const baseUrl = useSandbox ? getSandboxUrl() : getProductionUrl();
 
     if (result.success) {
       const tx = result.transaction;
@@ -235,7 +238,7 @@ ${JSON.stringify(result.error.details || result.error, null, 2)}
 1. **ERR_MISSING_TRANSACTION (404)**: Transaction not found in history
 2. **HTTP 429 (Too Many Requests)**: API is throttled, implement retry logic
 3. **Authentication Issues**: Verify JWT token and partner credentials
-4. **Transaction Still Active**: Use \`payware_pi_get_transaction_status\` for active transactions
+4. **Transaction Still Active**: Use \`payware_operations_get_transaction_status\` for active transactions
 
 **Troubleshooting:**
 1. Verify transaction ID is correct: 10 characters total, starts with 'pw' (standard), 'pr' (product), or 'ps' (soundbite)
@@ -251,7 +254,7 @@ ${JSON.stringify(result.error.details || result.error, null, 2)}
 - Avoid excessive polling of this endpoint
 
 **Alternative Actions:**
-- If transaction is still active: Use \`payware_pi_get_transaction_status\`
+- If transaction is still active: Use \`payware_operations_get_transaction_status\`
 - If rate limited: Wait and retry after a delay
 - If transaction not found: Verify the transaction ID exists`
         }]