@payware/mcp-server 1.3.3 → 1.5.0

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

@@ -2,6 +2,7 @@ import axios from 'axios';
 import { createJWTForPartner } from '../../core/auth/jwt-factory.js';
 import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
 import { describeApiError } from '../../shared/api-errors.js';
+import { READS } from '../../shared/tool-annotations.js';
 
 /**
  * Get one completed transaction as an ISV acting on behalf of a merchant.
@@ -68,6 +69,7 @@ export async function getTransactionHistory({
 
 export const getTransactionHistoryTool = {
   name: 'payware_operations_get_transaction_history',
+  annotations: READS,
   description: `Get one completed or expired transaction as an ISV on behalf of a merchant.
 
 **Endpoint:** GET /transactions-history/{transactionId}

package/src/merchant/data/export-report.js

@@ -1,11 +1,13 @@
 import { exportReport, EXPORT_FORMATS } from '../../shared/data/data-api.js';
 import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { CREATES } from '../../shared/tool-annotations.js';
 
 /**
  * Export report tool for merchants
  */
 export const exportReportTool = {
   name: "payware_data_export_report",
+  annotations: CREATES,
   description: "Export a READY report in a specific format (PDF, CSV, Excel, JSON). The report must be in READY status first.",
   inputSchema: {
     type: "object",

package/src/merchant/data/generate-report.js

@@ -1,11 +1,13 @@
 import { generateReport, REPORT_TYPES, LOCALES } from '../../shared/data/data-api.js';
 import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { CREATES } from '../../shared/tool-annotations.js';
 
 /**
  * Generate report tool for merchants
  */
 export const generateReportTool = {
   name: "payware_data_generate_report",
+  annotations: CREATES,
   description: `Generate an asynchronous data report for merchant data analysis and reporting. Production only - not supported in sandbox.
 
 ⚠️ **Running a report is entitlement-checked as of 2026-08-22.** Naming a report answers **403

package/src/merchant/data/get-export-list.js

@@ -1,11 +1,13 @@
 import { getExportList } from '../../shared/data/data-api.js';
 import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { READS } from '../../shared/tool-annotations.js';
 
 /**
  * Get export list for request tool for merchants
  */
 export const getExportListTool = {
   name: "payware_data_get_export_list",
+  annotations: READS,
   description: "Get all export attempts for a specific report request. Returns list of exports in various formats with their status and download information. Production only - not supported in sandbox.",
   inputSchema: {
     type: "object",

package/src/merchant/data/get-report-requests.js

@@ -1,11 +1,13 @@
 import { getReportRequests, REPORT_TYPES } from '../../shared/data/data-api.js';
 import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { READS } from '../../shared/tool-annotations.js';
 
 /**
  * Get report request history tool for merchants
  */
 export const getReportRequestsTool = {
   name: "payware_data_get_report_requests",
+  annotations: READS,
   description: "Get all execution requests for a specific report type. Returns historical execution records with status and parameters. Production only - not supported in sandbox.",
   inputSchema: {
     type: "object",

package/src/merchant/data/get-report-status.js

@@ -1,11 +1,13 @@
 import { getReportStatus } from '../../shared/data/data-api.js';
 import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { READS } from '../../shared/tool-annotations.js';
 
 /**
  * Get report status tool for merchants
  */
 export const getReportStatusTool = {
   name: "payware_data_get_report_status",
+  annotations: READS,
   description: "Get the status of an asynchronous report generation request. Use this to monitor report progress.",
   inputSchema: {
     type: "object",

package/src/merchant/data/index.js

@@ -20,12 +20,14 @@ import { exportReportTool } from './export-report.js';
 import { listReportsTool } from './list-reports.js';
 import { getReportRequestsTool } from './get-report-requests.js';
 import { getExportListTool } from './get-export-list.js';
+import { ADDS, CHANGES, READS } from '../../shared/tool-annotations.js';
 
 /**
  * Get export status tool for merchants
  */
 export const getExportStatusTool = {
   name: "payware_data_get_export_status",
+  annotations: READS,
   description: "Get the status of a report export request. Use this to monitor export progress.",
   inputSchema: {
     type: "object",
@@ -41,8 +43,7 @@ export const getExportStatusTool = {
       },
       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."
       }
     },
     required: ["exportId"]
@@ -117,6 +118,7 @@ ${downloadInfo}
  */
 export const downloadExportTool = {
   name: "payware_data_download_export",
+  annotations: ADDS,
   description: "Download a READY export file. The export must be in READY status. Returns binary data for the file.",
   inputSchema: {
     type: "object",
@@ -127,7 +129,7 @@ export const downloadExportTool = {
       },
       saveToFile: {
         type: "boolean",
-        description: "Whether to save the downloaded file to disk. If true, saves to /mnt/d/git/payware/mcp/downloads/. If false, only shows metadata/preview.",
+        description: "Whether to save the downloaded file to disk. If true, saves it to a payware-mcp-downloads folder in the system temp directory and returns the path. If false, only shows metadata/preview.",
         default: false
       },
       partnerId: {
@@ -181,11 +183,14 @@ export const downloadExportTool = {
         };
         const extension = extensionMap[contentType] || 'bin';
         const filename = `report_${exportId.substring(0, 8)}.${extension}`;
-        const filepath = `/mnt/d/git/payware/mcp/downloads/${filename}`;
+        // The temp directory is writable wherever the server runs; its working directory, set by the
+        // MCP client, often is not. This was a fixed developer path, which no other machine has.
+        const os = await import('os');
+        const path = await import('path');
+        const filepath = path.join(os.tmpdir(), 'payware-mcp-downloads', filename);
 
         // Save file to downloads directory
         const fs = await import('fs');
-        const path = await import('path');
         const downloadDir = path.dirname(filepath);
 
         // Create downloads directory if it doesn't exist
@@ -222,7 +227,7 @@ ${savedFileInfo}${contentPreview}
 **Summary:**
 ✅ ${saveToFile ? 'File saved to disk and' : 'File'} downloaded successfully
 
-${saveToFile ? '**Tip:** The file has been saved and can be opened with the appropriate application.' : '**Tip:** Use `saveToFile: true` parameter to save the file to disk at `/mnt/d/git/payware/mcp/downloads/`'}`
+${saveToFile ? '**Tip:** The file has been saved and can be opened with the appropriate application.' : '**Tip:** Use `saveToFile: true` parameter to save the file to disk'}`
         }]
       };
     } catch (error) {
@@ -236,6 +241,7 @@ ${saveToFile ? '**Tip:** The file has been saved and can be opened with the appr
  */
 export const cancelReportTool = {
   name: "payware_data_cancel_report",
+  annotations: CHANGES,
   description: "Cancel a running report generation. Only reports in QUEUED status can be cancelled.",
   inputSchema: {
     type: "object",
@@ -251,8 +257,7 @@ export const cancelReportTool = {
       },
       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."
       }
     },
     required: ["requestId"]
@@ -307,6 +312,7 @@ Only reports in QUEUED status can be cancelled. Reports that are already READY,
  */
 export const cancelExportTool = {
   name: "payware_data_cancel_export",
+  annotations: CHANGES,
   description: "Cancel a running export process. Only exports in QUEUED status can be cancelled.",
   inputSchema: {
     type: "object",
@@ -322,8 +328,7 @@ export const cancelExportTool = {
       },
       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."
       }
     },
     required: ["exportId"]

package/src/merchant/data/list-reports.js

@@ -1,11 +1,13 @@
 import { listReports } from '../../shared/data/data-api.js';
 import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { READS } from '../../shared/tool-annotations.js';
 
 /**
  * List all available reports tool for merchants
  */
 export const listReportsTool = {
   name: "payware_data_list_reports",
+  annotations: READS,
   description: "List all available report types with their configurations, descriptions, and visibility settings. Production only - not supported in sandbox.",
   inputSchema: {
     type: "object",

package/src/merchant/deep-links/delete-product-link.js

@@ -1,11 +1,13 @@
 import { deleteProductDeepLink } 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 merchant product
  */
 export const deleteProductLinkTool = {
   name: "payware_deep_links_delete_product_link",
+  annotations: CHANGES,
   description: `Delete an active deep link for a product. Once deleted, the deep link URL will no longer redirect to the payware mobile app.
 
 **Use Cases:**
@@ -33,8 +35,7 @@ export const deleteProductLinkTool = {
       },
       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: ["productId"]

package/src/merchant/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 merchant transaction
  */
 export const deleteTransactionLinkTool = {
   name: "payware_deep_links_delete_transaction_link",
+  annotations: CHANGES,
   description: `Delete an active deep link for a transaction. Once deleted, the deep link URL will no longer redirect to the payware mobile app.
 
 **Use Cases:**
@@ -33,8 +35,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/merchant/deep-links/get-product-link.js

@@ -1,16 +1,18 @@
 import { getProductDeepLink } 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 merchant product
  */
 export const getProductLinkTool = {
   name: "payware_deep_links_get_product_link",
-  description: `Get an active deep link for a product. Returns a clickable URL that redirects to the payware mobile app.
+  annotations: ADDS,
+  description: `Get an active deep link for a product. Returns a clickable URL that redirects to the payware mobile app. For a link whose payments are attributed to one placement of the product (a poster, an ad, a mailing), use payware_products_get_placement_link instead.
 
 **Deep Link Format:**
 - Web URL: https://go.payware.eu/{productId}
-- Mobile Redirect: payware://{productId}
+- Mobile Redirect: payware:/{productId} (one slash: the identifier is case-sensitive, so it must not sit in the URI host, which redirect services lowercase)
 
 **Use Cases:**
 - Mobile-only e-commerce product references
@@ -19,6 +21,7 @@ export const getProductLinkTool = {
 
 **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 product
 - Traditional deep links that route to app content when app is installed`,
 
@@ -37,8 +40,7 @@ export const getProductLinkTool = {
       },
       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: ["productId"]
@@ -82,7 +84,7 @@ export const getProductLinkTool = {
 **Deep Link Details:**
 - Product ID: ${productId}
 - Web URL: ${linkUrl}
-- Mobile Redirect: payware://${productId}
+- Mobile Redirect: payware:/${productId}
 
 **Link Information:**
 - Status: Active
@@ -101,7 +103,7 @@ ${JSON.stringify(result.data, null, 2)}
 
 **Usage:**
 1. Share the web URL: \`${linkUrl}\`
-2. On mobile devices, it will redirect to: \`payware://${productId}\`
+2. On mobile devices, it will redirect to: \`payware:/${productId}\`
 3. Link expires when the product expires
 4. Recreate if product is updated`
         }]

package/src/merchant/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 merchant transaction
  */
 export const getTransactionLinkTool = {
   name: "payware_deep_links_get_transaction_link",
+  annotations: ADDS,
   description: `Get an active deep link for a transaction. 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 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
 - Traditional deep links that route to app content when app is installed`,
 
@@ -37,8 +40,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"]
@@ -82,7 +84,7 @@ export const getTransactionLinkTool = {
 **Deep Link Details:**
 - Transaction ID: ${transactionId}
 - Web URL: ${linkUrl}
-- Mobile Redirect: payware://${transactionId}
+- Mobile Redirect: payware:/${transactionId}
 
 **Link Information:**
 - Status: Active
@@ -101,7 +103,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. Recreate if transaction is extended`
         }]
@@ -123,7 +125,7 @@ ${JSON.stringify(result.data, null, 2)}
 4. **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 transaction is not expired`

package/src/merchant/index.js

@@ -26,6 +26,9 @@ import { merchantLogsTools } from './logs/index.js';
 // Shop tools - needed before any call that takes a shop / shopCode
 import { merchantShopTools } from './shops/index.js';
 
+// Campaigns, placements and airings - one definition shared by merchants and ISVs
+import { placementTools } from '../shared/placements/tools.js';
+
 // Shared utility tools
 import { getServerInfoTool } from '../utils/server-info.js';
 
@@ -60,7 +63,10 @@ export const merchantTools = [
   ...merchantLogsTools,
 
   // Shop lookup
-  ...merchantShopTools
+  ...merchantShopTools,
+
+  // Campaigns, placements and airings
+  ...placementTools('merchant')
 ];
 
 /**

package/src/merchant/logs/index.js

@@ -12,12 +12,14 @@ import {
   LOG_LEVELS
 } from '../../shared/logs/logs-api.js';
 import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { LOCAL, READS } from '../../shared/tool-annotations.js';
 
 /**
  * Query logs tool for merchants
  */
 export const queryLogsTool = {
   name: "payware_logs_query",
+  annotations: READS,
   description: "Query application logs with filters. Premium plan required. Returns paginated JSON log entries for debugging and monitoring your integration.",
   inputSchema: {
     type: "object",
@@ -174,6 +176,7 @@ Use cursor \`${nextCursor}\` to fetch the next page of results.` : ''}
  */
 export const getLogStatusTool = {
   name: "payware_logs_status",
+  annotations: READS,
   description: "Get log availability and storage information. Premium plan required. Shows if logs are available, total size, and file count.",
   inputSchema: {
     type: "object",
@@ -262,6 +265,7 @@ ${data.logsAvailable ? `
  */
 export const getLogDownloadUrlTool = {
   name: "payware_logs_download_url",
+  annotations: LOCAL,
   description: "Get download URL for logs archive. Premium plan required. Returns URL for downloading logs as gzipped JSON file.",
   inputSchema: {
     type: "object",

package/src/merchant/products/audios.js

@@ -6,15 +6,17 @@ import {
   deleteAudio
 } from '../../shared/products/products-api.js';
 import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { CHANGES, CREATES, READS } from '../../shared/tool-annotations.js';
 
 /**
  * Register audio tool implementation for merchants
  */
 export const registerAudioTool = {
   name: "payware_products_register_audio",
+  annotations: CREATES,
   description: `Register an audio file (soundbite) for a product to enable audio-based payment initiation.
 
-**Supported formats:** Most audio/video formats (up to 200MB)
+**Supported formats:** MP3, WAV, OGG, M4A, FLAC, AAC, WMA, MP4, MOV, up to 100 MB, holding 2 to 120 seconds of audio
 **Note:** For video files, only the audio channel is registered`,
 
   inputSchema: {
@@ -36,8 +38,7 @@ export const registerAudioTool = {
       },
       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",
@@ -126,8 +127,8 @@ ${audio.status === '1' ? '✅ Audio is ready for use in soundbite transactions'
 
 **Troubleshooting:**
 1. Verify the audio file path exists and is accessible
-2. Check file size (max 200MB)
-3. Ensure supported audio/video format
+2. Check file size (max 100 MB) and length (2 to 120 seconds of audio)
+3. Ensure the format is MP3, WAV, OGG, M4A, FLAC, AAC, WMA, MP4 or MOV
 4. Verify the product ID exists and belongs to your account
 5. Check available storage space`
         }]
@@ -141,6 +142,7 @@ ${audio.status === '1' ? '✅ Audio is ready for use in soundbite transactions'
  */
 export const getAudiosTool = {
   name: "payware_products_get_audios",
+  annotations: READS,
   description: "Get all registered audio files for a product",
 
   inputSchema: {
@@ -158,8 +160,7 @@ export const getAudiosTool = {
       },
       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",
@@ -253,6 +254,7 @@ ${audiosList}
  */
 export const getAudioTool = {
   name: "payware_products_get_audio",
+  annotations: READS,
   description: "Get detailed information about a specific audio file",
 
   inputSchema: {
@@ -274,8 +276,7 @@ export const getAudioTool = {
       },
       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",
@@ -367,6 +368,7 @@ ${audio.status === '1' ? '✅ **Ready:** Audio is processed and ready for soundb
  */
 export const updateAudioTool = {
   name: "payware_products_update_audio",
+  annotations: CHANGES,
   description: "Update audio information (title) or reassign audio to another product",
 
   inputSchema: {
@@ -388,7 +390,7 @@ export const updateAudioTool = {
       },
       newProductId: {
         type: "string",
-        description: "New product ID to reassign audio to (starts with 'pr')",
+        description: "Product to move the audio to (starts with 'pr'). Sent as a transfer, which keeps the fingerprint; the target must be in the same shop",
         pattern: "^pr[a-zA-Z0-9]+$"
       },
       partnerId: {
@@ -398,8 +400,7 @@ export const updateAudioTool = {
       },
       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",
@@ -501,6 +502,7 @@ ${JSON.stringify(audio, null, 2)}
  */
 export const deleteAudioTool = {
   name: "payware_products_delete_audio",
+  annotations: CHANGES,
   description: "Delete an audio file from a product. This action cannot be undone.",
 
   inputSchema: {
@@ -522,8 +524,7 @@ export const deleteAudioTool = {
       },
       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/create-product.js

@@ -1,12 +1,14 @@
 import { createProduct } 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 { CREATES } from '../../shared/tool-annotations.js';
 
 /**
  * Create product tool implementation for merchants
  */
 export const createProductTool = {
   name: "payware_products_create_product",
+  annotations: CREATES,
   description: `Create a new product for inventory management and payment processing.
 
 **Product Structure:**
@@ -134,8 +136,7 @@ export const createProductTool = {
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for authentication (uses environment-specific private key as default)",
-        default: getPrivateKeySafe(true)
+        description: "RSA private key for authentication (uses environment-specific private key as default)"
       },
       useSandbox: {
         type: "boolean",

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

@@ -1,11 +1,13 @@
 import { deleteProduct } from '../../shared/products/products-api.js';
 import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { CHANGES } from '../../shared/tool-annotations.js';
 
 /**
  * Delete product tool implementation for merchants
  */
 export const deleteProductTool = {
   name: "payware_products_delete_product",
+  annotations: CHANGES,
   description: "Delete a product from the merchant account. This action cannot be undone.",
 
   inputSchema: {
@@ -23,8 +25,7 @@ export const deleteProductTool = {
       },
       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/get-product-image.js

@@ -1,12 +1,14 @@
 import { getProductImage } from '../../shared/products/products-api.js';
 import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
 import { IMAGE_TYPES, IMAGE_FORMATS, QR_ERROR_CORRECTION, BARCODE_LOCATIONS } from '../../shared/products/products-api.js';
+import { READS } from '../../shared/tool-annotations.js';
 
 /**
  * Get product image tool implementation for merchants
  */
 export const getProductImageTool = {
   name: "payware_products_get_product_image",
+  annotations: READS,
   description: `Generate a QR code or barcode image for a product.
 
 **QR Code Options:** Format, border, error correction, scale, version
@@ -102,8 +104,7 @@ export const getProductImageTool = {
       },
       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/get-product.js

@@ -1,11 +1,13 @@
 import { getProduct } from '../../shared/products/products-api.js';
 import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { READS } from '../../shared/tool-annotations.js';
 
 /**
  * Get product tool implementation for merchants
  */
 export const getProductTool = {
   name: "payware_products_get_product",
+  annotations: READS,
   description: "Get detailed information about a specific product by ID",
 
   inputSchema: {
@@ -23,8 +25,7 @@ export const getProductTool = {
       },
       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",