@payware/mcp-server 1.3.2 → 1.4.0

package/src/isv/products/audios.js

@@ -6,6 +6,7 @@ import {
   deleteAudio
 } from '../../shared/products/products-api.js';
 import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { CHANGES, CREATES, READS } from '../../shared/tool-annotations.js';
 
 // Common ISV authentication properties
 const ISV_AUTH_PROPS = {
@@ -46,9 +47,10 @@ function validateISVAuth(args) {
  */
 export const registerAudioTool = {
   name: "payware_products_register_audio",
+  annotations: CREATES,
   description: `Register an audio file (soundbite) for a merchant's product (ISV operation).
 
-**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: {
@@ -139,6 +141,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 merchant's product (ISV operation)",
 
   inputSchema: {
@@ -225,6 +228,7 @@ ${audiosList}`
  */
 export const getAudioTool = {
   name: "payware_products_get_audio",
+  annotations: READS,
   description: "Get detailed information about a specific audio file (ISV operation)",
 
   inputSchema: {
@@ -305,6 +309,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 (ISV operation)",
 
   inputSchema: {
@@ -327,7 +332,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]+$"
       },
       useSandbox: {
@@ -400,6 +405,7 @@ ${newProductId ? `- Reassigned from product ${productId} to ${newProductId}` : '
  */
 export const deleteAudioTool = {
   name: "payware_products_delete_audio",
+  annotations: CHANGES,
   description: "Delete an audio file from a merchant's product (ISV operation). This action cannot be undone.",
 
   inputSchema: {

package/src/isv/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 ISVs
  */
 export const createProductTool = {
   name: "payware_products_create_product",
+  annotations: CREATES,
   description: `Create a new product for inventory management and payment processing on behalf of a merchant (ISV operation).
 
 **ISV Authentication**: Requires ISV credentials and OAuth2 token from target merchant.

package/src/isv/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 ISVs
  */
 export const deleteProductTool = {
   name: "payware_products_delete_product",
+  annotations: CHANGES,
   description: "Delete a product from a merchant account (ISV operation). This action cannot be undone.",
 
   inputSchema: {

package/src/isv/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 ISVs
  */
 export const getProductImageTool = {
   name: "payware_products_get_product_image",
+  annotations: READS,
   description: `Generate a QR code or barcode image for a merchant's product (ISV operation).`,
 
   inputSchema: {

package/src/isv/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 ISVs
  */
 export const getProductTool = {
   name: "payware_products_get_product",
+  annotations: READS,
   description: "Get detailed information about a specific product by ID (ISV operation)",
 
   inputSchema: {

package/src/isv/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 ISVs
  */
 export const listProductsTool = {
   name: "payware_products_list_products",
+  annotations: READS,
   description: "Get a list of all products for a merchant account (ISV operation)",
 
   inputSchema: {

package/src/isv/products/schedules.js

@@ -7,6 +7,7 @@ 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';
 
 // Common ISV authentication properties
 const ISV_AUTH_PROPS = {
@@ -47,6 +48,7 @@ function validateISVAuth(args) {
  */
 export const createScheduleTool = {
   name: "payware_products_create_schedule",
+  annotations: CREATES,
   description: "Create a price schedule for a merchant's product (ISV operation)",
 
   inputSchema: {
@@ -172,6 +174,7 @@ export const createScheduleTool = {
  */
 export const getSchedulesTool = {
   name: "payware_products_get_schedules",
+  annotations: READS,
   description: "Get all price schedules for a merchant's product (ISV operation)",
 
   inputSchema: {
@@ -258,6 +261,7 @@ ${schedulesList}`
  */
 export const getScheduleTool = {
   name: "payware_products_get_schedule",
+  annotations: READS,
   description: "Get detailed information about a specific price schedule (ISV operation)",
 
   inputSchema: {
@@ -341,6 +345,7 @@ export const getScheduleTool = {
  */
 export const updateScheduleTool = {
   name: "payware_products_update_schedule",
+  annotations: CHANGES,
   description: "Update an existing price schedule (ISV operation)",
 
   inputSchema: {
@@ -452,6 +457,7 @@ export const updateScheduleTool = {
  */
 export const deleteScheduleTool = {
   name: "payware_products_delete_schedule",
+  annotations: CHANGES,
   description: "Delete a price schedule (ISV operation). This action cannot be undone.",
 
   inputSchema: {

package/src/isv/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 ISVs
  */
 export const updateProductTool = {
   name: "payware_products_update_product",
+  annotations: CHANGES,
   description: `Update an existing product on behalf of a merchant (ISV operation). Only provide the fields you want to change.`,
 
   inputSchema: {

package/src/isv/reference/index.js

@@ -2,6 +2,7 @@ import axios from 'axios';
 import { createJWTToken } from '../../core/auth/jwt-token.js';
 import { apiErrorResult } from '../../shared/api-errors.js';
 import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { READS } from '../../shared/tool-annotations.js';
 
 /**
  * Reference data - the enumerations a merchant registration form has to be filled in with.
@@ -129,6 +130,7 @@ const DATASET_DOCS = Object.entries(DATASETS)
 
 export const referenceDataTool = {
   name: 'payware_reference_lookup',
+  annotations: READS,
   description: `Look up payware reference data - the enumerations a merchant registration form needs.
 
 **Endpoints:** GET /isv/reference/{legal-forms, business-activities, currencies, languages, jurisdictions}

package/src/isv/transactions/cancel-transaction.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 { CHANGES } from '../../shared/tool-annotations.js';
 
 /**
  * Cancel a transaction via payware API as an ISV
@@ -77,6 +78,7 @@ export async function cancelTransaction({ transactionId, statusMessage, merchant
 
 export const cancelTransactionTool = {
   name: 'payware_operations_cancel_transaction',
+  annotations: CHANGES,
   description: `Cancel an active transaction as an ISV on behalf of a merchant.
 
 **Endpoint:** PATCH /transactions/{transactionId} with \`{"status":"CANCELLED","statusMessage":"..."}\`

package/src/isv/transactions/create-transaction.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 { CREATES } from '../../shared/tool-annotations.js';
 
 /**
  * Create a transaction via payware API on behalf of a merchant (ISV)
@@ -145,6 +146,7 @@ export async function createTransaction({
 
 export const createTransactionTool = {
   name: 'payware_operations_create_transaction',
+  annotations: CREATES,
   description: `Create a new transaction through payware as an ISV on behalf of a merchant.
 
 ISV partners can create transactions for merchants they have authorization for via OAuth2.

package/src/isv/transactions/get-status.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 { apiErrorResult } from '../../shared/api-errors.js';
+import { READS } from '../../shared/tool-annotations.js';
 
 /**
  * Get transaction status from payware API as an ISV
@@ -81,12 +82,13 @@ function formatTransactionStatus(transaction) {
  */
 export const getTransactionStatusTool = {
   name: "payware_operations_get_transaction_status",
+  annotations: READS,
   description: `Get status of an ACTIVE transaction by ID as an ISV on behalf of a merchant.
 
 **ISV Authentication:** Uses ISV JWT with merchant partner ID in 'aud' claim and OAuth2 token in 'sub' claim.
 **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.
 
 **Required:** Merchant Partner ID and OAuth2 token for ISV authentication.
 

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

@@ -3,6 +3,7 @@ import { createJWTForPartner } from '../../core/auth/jwt-factory.js';
 import { createMinimizedJSON } from '../../core/utils/json-serializer.js';
 import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
 import { describeApiError } from '../../shared/api-errors.js';
+import { COMMITS } from '../../shared/tool-annotations.js';
 
 /**
  * Process a PEER transaction as an ISV on behalf of a merchant.
@@ -122,6 +123,7 @@ export async function processTransaction({
 
 export const processTransactionTool = {
   name: 'payware_operations_process_transaction',
+  annotations: COMMITS,
   description: `Process a PEER transaction as an ISV on behalf of a merchant - the merchant scanning a customer's QR or barcode to collect payment.
 
 **Endpoint:** POST /transactions/{transactionId}

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

@@ -1,5 +1,6 @@
 import { getPartnerIdSafe } from '../../config/env.js';
 import { generateMockCallback, simulateCallbackDelivery } from '../../merchant/transactions/simulate-callback.js';
+import { LOCAL } from '../../shared/tool-annotations.js';
 
 /**
  * Simulate the callback a merchant's endpoint receives, for an ISV building that handler.
@@ -17,16 +18,19 @@ import { generateMockCallback, simulateCallbackDelivery } from '../../merchant/t
  */
 export const simulateCallbackTool = {
   name: 'payware_operations_simulate_callback',
+  annotations: LOCAL,
   description: `Simulate the callback payload payware sends to a merchant's callbackUrl, for building and testing a webhook handler as an ISV.
 
 **Local only - this makes no API call.** payware has no endpoint that triggers a callback on demand,
 so nothing here reaches the network. What you get back is the exact payload shape a real
 TRANSACTION_FINALIZED callback carries, which is what a handler needs in order to be written.
 
-**Callbacks go to the MERCHANT's callbackUrl, not to yours.** An ISV that needs to know a transaction
-finished either has the merchant forward it, or polls
-\`payware_operations_get_transaction_history\` for the ids it created. Simulating the payload here
-tells you what the merchant's endpoint will receive; it does not route anything to you.
+**Where the callback goes.** A transaction you create on a merchant's behalf calls back to the
+\`callbackUrl\` you give when creating it; a POI sale calls back to the POI's \`callbackUrl\`. Both are
+signed with your ISV callback key, so verify them with your own payware public key. Give no callbackUrl
+and that transaction sends no callbacks at all - the merchant's default URL is not used. Without a backend, follow the
+transaction with \`payware_operations_get_transaction_status\` while it is ACTIVE and then
+\`payware_operations_get_transaction_history\` once, or a POI sale with \`payware_poi_get_status\`.
 
 Four properties of the real payload that are easy to get wrong:
 
@@ -38,9 +42,11 @@ Four properties of the real payload that are easy to get wrong:
 **3. \`EXPIRED\` is a non-payment, not a failure.** The payer never paid within \`timeToLive\`. Release
 the order or the stock; do not treat it as an error to retry.
 
-**4. Deduplicate on \`(transactionId, callbackType)\`.** payware retries once a second, up to 15
-times, until the endpoint answers 200. That pair is stable across retries and is the key payware
-guarantees.
+**4. Deduplicate on \`(transactionId, callbackType)\`.** payware retries up to 15 times, backing off
+from about a second to at most 5 minutes between attempts, until the endpoint answers any 2xx. That
+pair is stable across retries and is the key payware guarantees.
+
+A POI sale's callback also carries \`poiId\`, the POI that created the transaction.
 
 **Not on this payload:** \`deliveryAddress\` (removed 2026-08-07 - fetch it from
 \`payware_operations_get_transaction_history\`), \`producerPartnerId\`, \`transactionType\` and
@@ -99,6 +105,10 @@ guarantees.
         enum: ['A2A', 'CARD_FUNDED', 'BNPL', 'INSTANT_CREDIT'],
         description: 'Payment method chosen by the customer. A2A = direct transfer. CARD_FUNDED = card-linked account. BNPL = buy now pay later. INSTANT_CREDIT = credit line.'
       },
+      poiId: {
+        type: 'string',
+        description: 'Set to simulate a POI sale: the callback then carries the poiId of the POI that created the transaction'
+      },
       merchantPartnerId: {
         type: 'string',
         description: 'Partner ID of the merchant whose callback this simulates. Used for labelling only - no call is made on their behalf.'
@@ -123,6 +133,7 @@ guarantees.
       feeRate = '0.0150',
       statusMessage,
       paymentMethod,
+      poiId,
       merchantPartnerId
     } = args;
 
@@ -131,7 +142,7 @@ guarantees.
     }
 
     const payload = generateMockCallback(transactionId, status, {
-      amount, currency, fee, feeFixed, feeRate, statusMessage, paymentMethod
+      amount, currency, fee, feeFixed, feeRate, statusMessage, paymentMethod, poiId
     });
 
     const delivery = callbackUrl ? await simulateCallbackDelivery(callbackUrl, payload) : null;
@@ -141,7 +152,7 @@ guarantees.
         type: 'text',
         text: `🔔 **Simulated Callback Payload**${merchantPartnerId ? ` (ISV ${getPartnerIdSafe()} -> Merchant ${merchantPartnerId})` : ''}
 
-This is what payware would POST to the **merchant's** \`callbackUrl\`. No request was made.
+This is what payware would POST to the transaction's (or POI's) \`callbackUrl\`. No request was made.
 
 \`\`\`json
 ${JSON.stringify(payload, null, 2)}
@@ -153,7 +164,7 @@ ${delivery.note}
 ` : '**No callbackUrl given** - payload only.'}
 
 **Building the handler:**
-1. Answer **200** or payware retries - once a second, 15 times.
+1. Answer any **2xx** or payware retries - up to 15 times, backing off from about a second to 5 minutes.
 2. Deduplicate on \`(transactionId, callbackType)\`; retries repeat the same pair.
 3. Read properties defensively: absent means absent, never zero.
 4. Treat \`EXPIRED\` as a non-payment, not an error to retry.

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