@payware/mcp-server 1.3.2 → 1.4.0

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",
@@ -163,8 +164,8 @@ retry once the window passes. The failure result exposes this as \`error.throttl
       const formatInfo = formatTransactionHistory(result.transaction);
       
       // Format dates
-      const created = result.transaction.created ? new Date(result.transaction.created * 1000).toISOString() : 'N/A';
-      const finalized = result.transaction.finalized ? new Date(result.transaction.finalized * 1000).toISOString() : 'N/A';
+      const created = result.transaction.created ? new Date(result.transaction.created).toISOString() : 'N/A';
+      const finalized = result.transaction.finalized ? new Date(result.transaction.finalized).toISOString() : 'N/A';
       
       return {
         content: [{
@@ -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,10 +125,12 @@ 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;
-      const createdDate = tx.created ? new Date(tx.created * 1000).toISOString() : 'N/A';
+      const createdDate = tx.created ? new Date(tx.created).toISOString() : 'N/A';
 
       // Status emoji mapping
       const statusEmojis = {
@@ -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`
         }]

package/src/payment-institution/transactions/get-transaction-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 via payware API (active transactions)
@@ -54,6 +55,7 @@ export async function getPITransactionStatus({
  */
 export const getPITransactionStatusTool = {
   name: "payware_operations_get_transaction_status",
+  annotations: READS,
   description: `Get the current status of an active payware transaction as a financial institution.
 
 **Use Cases:**
@@ -96,7 +98,7 @@ Four rules a payer-facing app must follow:
 4. **A missing field is usually a plan boundary, not an error.** \`imageUrl\` and \`termsUrl\` are
    Standard and above; \`termsText\` and the descriptions are universal.
 
-For a \`pr\`/\`ps\` identifier the values are resolved live (product -> shop -> merchant fallback, then
+For a \`pr\`, \`pl\` or \`ps\` identifier the values are resolved live (product -> shop -> merchant fallback, then
 plan gating); for the resulting \`pw\` transaction they are the snapshot frozen at creation, so what
 you get always reflects what the payer could have been shown at scan time.
 
@@ -105,14 +107,14 @@ strings at the smallest unit their own currency can be paid in - not always two
 **the value to echo back unchanged at finalize**; \`feeFixed\` and \`feeRate\` are informational, and
 recomputing the fee from them is rejected with ERR_FEE_MISMATCH.
 
-**Note:** This endpoint only returns active transactions. Use \`payware_pi_get_transaction_history\` for completed/expired transactions.`,
+**Note:** This endpoint only returns active transactions. Use \`payware_operations_get_transaction_history\` for completed/expired transactions.`,
   inputSchema: {
     type: "object",
     properties: {
       transactionId: {
         type: "string",
-        description: "Transaction ID to check status. 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 check status. 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}$"
       },
       partnerId: {
         type: "string",
@@ -121,8 +123,7 @@ recomputing the fee from them is rejected with ERR_FEE_MISMATCH.
       },
       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",
@@ -159,10 +160,12 @@ recomputing the fee from them is rejected with ERR_FEE_MISMATCH.
       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;
-      const createdDate = tx.created ? new Date(tx.created * 1000).toISOString() : 'N/A';
+      const createdDate = tx.created ? new Date(tx.created).toISOString() : 'N/A';
 
       // Transaction type display
       const typeDisplay = tx.transactionType || 'DEFAULT';
@@ -209,8 +212,8 @@ ${JSON.stringify(result.transaction, null, 2)}
 **Next Steps:**
 1. ${!tx.payerAccount ? 'Transaction waiting for payer to process' : 'Transaction processed, waiting for finalization'}
 2. ${tx.timeToLive && parseInt(tx.timeToLive) < 60 ? '⚠️ Transaction expires soon!' : 'Monitor remaining TTL'}
-3. Use \`payware_pi_process_transaction\` if you need to process this transaction
-4. Use \`payware_pi_finalize_transaction\` to confirm/decline after processing
+3. Use \`payware_operations_process_transaction\` if you need to process this transaction
+4. Use \`payware_operations_finalize_transaction\` to confirm/decline after processing
 
 **⚠️ Transaction State:**
 - This is an **active** transaction
@@ -240,18 +243,18 @@ ${JSON.stringify(result.error.details || result.error, null, 2)}
 
 **Common Issues:**
 1. **ERR_MISSING_TRANSACTION (404)**: Transaction not found, expired, or already completed
-2. **Invalid Transaction ID**: Check transaction ID format (10 chars: 'pw'/'pr'/'ps' + 8 chars)
+2. **Invalid Transaction ID**: Check transaction ID format (10 chars: 'pw'/'pr'/'pl'/'ps' + 8 chars)
 3. **Authentication Issues**: Verify JWT token and partner credentials
 
 **Troubleshooting:**
-1. Verify transaction ID is correct: 10 characters total, starts with 'pw' (standard), 'pr' (product), or 'ps' (soundbite)
+1. Verify transaction ID is correct: 10 characters total, starts with 'pw' (standard), 'pr' (product), 'pl' (placement) or 'ps' (soundbite)
 2. Check if transaction has expired or been completed
-3. Use \`payware_pi_get_transaction_history\` for completed/expired transactions
+3. Use \`payware_operations_get_transaction_history\` for completed/expired transactions
 4. Verify your partner credentials and API access
 5. Ensure transaction was created or you have access to it
 
 **Alternative Actions:**
-- If transaction is completed: Use \`payware_pi_get_transaction_history\`
+- If transaction is completed: Use \`payware_operations_get_transaction_history\`
 - If transaction ID is wrong: Verify the correct transaction ID
 - If access issues: Check your payment institution credentials`
         }]

package/src/payment-institution/transactions/process-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 { COMMITS } from '../../shared/tool-annotations.js';
 
 /**
  * Process a transaction as a payment institution via payware API
@@ -112,6 +113,7 @@ export async function processPITransaction({
  */
 export const processPITransactionTool = {
   name: "payware_operations_process_transaction",
+  annotations: COMMITS,
   description: `Process a transaction as a payment institution. Payment institutions can process transactions created by others and must provide account/friendlyName details.
 
 **Use Cases:**
@@ -148,8 +150,8 @@ export const processPITransactionTool = {
     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}$"
       },
       account: {
         type: "string",
@@ -205,8 +207,7 @@ export const processPITransactionTool = {
       },
       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."
       },
       // Payment method for POI transactions
       paymentMethod: {
@@ -373,7 +374,7 @@ ${JSON.stringify(result.transaction, null, 2)}
 1. **TRANSACTION_PROCESSED** callback will be sent to counterparty
 2. Wait for callback notification to your URL (if provided)
 3. Monitor transaction status for completion
-4. Use \`payware_pi_finalize_transaction\` to confirm/decline the transaction
+4. Use \`payware_operations_finalize_transaction\` to confirm/decline the transaction
 5. Handle final TRANSACTION_FINALIZED callbacks
 
 **⚠️ Important:**
@@ -412,7 +413,7 @@ ${JSON.stringify(result.error.details || result.error, null, 2)}
 7. **ERR_SPECIFYING_CURRENCY_NOT_ALLOWED**: Cannot change currency on merchant transactions
 
 **Troubleshooting:**
-1. Verify transaction ID is correct: 10 characters total, starts with 'pw' (standard), 'pr' (product), or 'ps' (soundbite)
+1. Verify transaction ID is correct: 10 characters total, starts with 'pw' (standard), 'pr' (product), 'pl' (placement) or 'ps' (soundbite)
 2. Ensure account and friendlyName are provided
 3. Check currency matches original transaction currency
 4. Verify callback URL is provided (especially for payee role)