Make it clearer when many entities are affected

Author: danielmarbach

src/ServiceControl.UnitTests/Mcp/McpMetadataDescriptionsTests.cs

@@ -39,10 +39,32 @@ public void Retry_all_failed_messages_warns_that_it_affects_all_unresolved_faile
         Assert.That(description, Does.Contain("all unresolved failed messages across the instance"));
     }
 
+    [TestCase(typeof(RetryTools), nameof(RetryTools.RetryFailedMessages))]
+    [TestCase(typeof(RetryTools), nameof(RetryTools.RetryFailedMessagesByQueue))]
+    [TestCase(typeof(RetryTools), nameof(RetryTools.RetryAllFailedMessages))]
+    [TestCase(typeof(RetryTools), nameof(RetryTools.RetryAllFailedMessagesByEndpoint))]
+    [TestCase(typeof(RetryTools), nameof(RetryTools.RetryFailureGroup))]
+    [TestCase(typeof(ArchiveTools), nameof(ArchiveTools.ArchiveFailedMessages))]
+    [TestCase(typeof(ArchiveTools), nameof(ArchiveTools.ArchiveFailureGroup))]
+    [TestCase(typeof(ArchiveTools), nameof(ArchiveTools.UnarchiveFailedMessages))]
+    [TestCase(typeof(ArchiveTools), nameof(ArchiveTools.UnarchiveFailureGroup))]
+    public void Bulk_mutating_tools_warn_that_they_may_affect_many_messages(Type toolType, string methodName)
+    {
+        var description = GetMethodDescription(toolType, methodName);
+
+        Assert.That(description, Does.Contain("may affect many messages"));
+    }
+
     [TestCase(typeof(FailedMessageTools), nameof(FailedMessageTools.GetFailedMessageById), "failedMessageId", "failed message ID")]
     [TestCase(typeof(FailedMessageTools), nameof(FailedMessageTools.GetFailedMessageLastAttempt), "failedMessageId", "failed message ID")]
+    [TestCase(typeof(RetryTools), nameof(RetryTools.RetryFailedMessage), "failedMessageId", "failed message ID")]
+    [TestCase(typeof(RetryTools), nameof(RetryTools.RetryFailedMessages), "messageIds", "failed message IDs")]
     [TestCase(typeof(ArchiveTools), nameof(ArchiveTools.ArchiveFailureGroup), "groupId", "failure group ID")]
     [TestCase(typeof(ArchiveTools), nameof(ArchiveTools.UnarchiveFailureGroup), "groupId", "failure group ID")]
+    [TestCase(typeof(ArchiveTools), nameof(ArchiveTools.ArchiveFailedMessage), "failedMessageId", "failed message ID")]
+    [TestCase(typeof(ArchiveTools), nameof(ArchiveTools.ArchiveFailedMessages), "messageIds", "failed message IDs")]
+    [TestCase(typeof(ArchiveTools), nameof(ArchiveTools.UnarchiveFailedMessage), "failedMessageId", "failed message ID")]
+    [TestCase(typeof(ArchiveTools), nameof(ArchiveTools.UnarchiveFailedMessages), "messageIds", "failed message IDs")]
     public void Key_error_tool_parameters_identify_the_entity_type(Type toolType, string methodName, string parameterName, string expectedPhrase)
     {
         var description = GetParameterDescription(toolType, methodName, parameterName);

src/ServiceControl/Mcp/RetryTools.cs

@@ -43,6 +43,7 @@ public async Task<string> RetryFailedMessage(
     [McpServerTool(ReadOnly = false, Idempotent = false, Destructive = true, OpenWorld = false), Description(
         "Use this tool to reprocess multiple specific failed messages at once. " +
         "This operation changes system state. " +
+        "It may affect many messages. " +
         "Good for questions like: 'retry these messages', 'reprocess messages msg-1, msg-2, msg-3', or 'retry this batch'. " +
         "Prefer RetryFailureGroup when all messages share the same failure cause — use this tool when you have a specific set of message IDs to retry."
     )]
@@ -64,6 +65,7 @@ public async Task<string> RetryFailedMessages(
     [McpServerTool(ReadOnly = false, Idempotent = false, Destructive = true, OpenWorld = false), Description(
         "Use this tool to retry all unresolved failed messages from a specific queue. " +
         "This operation changes system state. " +
+        "It may affect many messages. " +
         "Good for questions like: 'retry all failures in the Sales queue', 'reprocess everything from this queue', or 'the queue consumer is back, retry its failures'. " +
         "Useful when a queue's consumer was down or misconfigured and is now fixed. Only retries messages with unresolved status."
     )]
@@ -83,6 +85,7 @@ await messageSession.SendLocal<RetryMessagesByQueueAddress>(m =>
     [McpServerTool(ReadOnly = false, Idempotent = false, Destructive = true, OpenWorld = false), Description(
         "Use this tool to retry every unresolved failed message across all queues and endpoints. " +
         "This operation changes system state. " +
+        "It may affect many messages. " +
         "Good for questions like: 'retry everything', 'reprocess all failures', or 'retry all failed messages'. " +
         "It affects all unresolved failed messages across the instance. " +
         "This is a broad operation — prefer RetryFailedMessagesByQueue, RetryAllFailedMessagesByEndpoint, or RetryFailureGroup when you can scope the retry more narrowly."
@@ -98,6 +101,7 @@ public async Task<string> RetryAllFailedMessages()
     [McpServerTool(ReadOnly = false, Idempotent = false, Destructive = true, OpenWorld = false), Description(
         "Use this tool to retry all failed messages for a specific NServiceBus endpoint. " +
         "This operation changes system state. " +
+        "It may affect many messages. " +
         "Good for questions like: 'retry all failures in the Sales endpoint', 'the bug in Shipping is fixed, retry its failures', or 'reprocess all errors for this endpoint'. " +
         "Useful when a bug in one endpoint has been fixed and all its failures should be reprocessed."
     )]
@@ -113,9 +117,10 @@ public async Task<string> RetryAllFailedMessagesByEndpoint(
     [McpServerTool(ReadOnly = false, Idempotent = false, Destructive = true, OpenWorld = false), Description(
         "Use this tool to retry all failed messages that share the same exception type and stack trace. " +
         "This operation changes system state. " +
+        "It may affect many messages. " +
         "Good for questions like: 'retry this failure group', 'the bug causing these NullReferenceExceptions is fixed, retry them', or 'retry all messages in this group'. " +
         "This is the most targeted way to retry related failures after fixing a specific bug. " +
-        "You need a group ID, which you can get from GetFailureGroups. " +
+        "You need a failure group ID, which you can get from GetFailureGroups. " +
         "Returns InProgress if a retry is already running for this group."
     )]
     public async Task<string> RetryFailureGroup(