refactored update bluesky connection tool. now accepts both handle and did.

tools/bluesky/update_bluesky_connection.py

···
 import os
 from typing import Dict, Literal
+from atproto import Client, models, AtUri
+
 
 def update_bluesky_connection(
     change_type: Literal["follow", "unfollow", "mute", "unmute", "block", "unblock"],
     actor: str
 ) -> Dict:
     """
-    Update connection status with a Bluesky user (follow, unfollow, mute, unmute, block, unblock).
+    Manage social connections with Bluesky users through follow, mute, and block actions.
+
+    This tool allows you to update your relationship with other Bluesky users by following/
+    unfollowing them, muting/unmuting their content, or blocking/unblocking them. The tool
+    intelligently checks the current connection state before taking action and reports whether
+    changes were made. Use this tool to manage your social graph and control what content
+    you see on Bluesky.
+
+    Connection types explained:
+    - Follow/Unfollow: Subscribe or unsubscribe from a user's posts in your feed
+    - Mute/Unmute: Hide a user's posts and replies from your feed without unfollowing
+      (they won't be notified). Muting is softer than blocking.
+    - Block/Unblock: Prevent all interaction with a user bidirectionally. Blocking prevents
+      them from seeing your content and you from seeing theirs. This is the strongest action.
 
     Args:
-        change_type (str): Type of connection change - "follow", "unfollow", "mute", "unmute", "block", or "unblock".
-        actor (str): The actor identifier (DID like 'did:plc:...' or handle like 'user.bsky.social').
+        change_type (Literal): The type of connection change to make. Must be one of:
+
+            - "follow": Subscribe to the user's posts. Their content will appear in your feed.
+              The user will be notified that you followed them.
+
+            - "unfollow": Unsubscribe from the user's posts. Their content will no longer appear
+              in your feed. The user may notice you unfollowed them.
+
+            - "mute": Hide the user's posts and replies from your feed without unfollowing them.
+              This is private - the user is not notified. Use this to reduce noise while
+              maintaining the connection. The user can still interact with your content.
+
+            - "unmute": Resume seeing the user's posts and replies in your feed. Removes a
+              previous mute. This is private - the user is not notified.
+
+            - "block": Prevent all interaction with the user bidirectionally. They cannot see
+              your posts or interact with them, and you cannot see theirs. This is the strongest
+              moderation action. The user may infer they've been blocked.
+
+            - "unblock": Remove a block and restore the ability for both of you to see and
+              interact with each other's content. Does not automatically re-follow.
+
+            This parameter is required and must be exactly one of the values listed above.
+
+        actor (str): The identifier for the Bluesky user to update the connection with.
+            This parameter is required and cannot be empty.
+
+            Accepts two formats:
+            - Handle: The user's full handle including domain suffix
+              Examples: "alice.bsky.social", "nytimes.com", "user.example.org"
+            - DID: The user's decentralized identifier starting with "did:plc:"
+              Example: "did:plc:z72i7hdynmk6r22z27h6tvur"
+
+            IMPORTANT: The tool automatically resolves handles to DIDs before performing
+            any operations. If you provide a handle, the tool will first fetch the user's
+            profile to get their DID, then use the DID for all connection operations. This
+            ensures reliability and consistency. If you already have a DID, it will be used
+            directly without additional lookups.
+
+            You can obtain actor identifiers from tools like search_bluesky or
+            get_bluesky_user_info.
 
     Returns:
-        Dict: Status and details of the connection change.
+        Dict: A dictionary containing the operation result with the following keys:
+
+            Common keys (all operations):
+            - status (str): Either "success" or "error"
+            - change_type (str): The type of change that was requested
+            - actor (dict): Information about the target user with keys:
+                - did (str): The user's DID
+                - handle (str): The user's handle
+                - display_name (str): The user's display name
+            - message (str): Human-readable description of what happened
+            - action_taken (bool): Whether a change was actually made (False if already
+              in the desired state)
+
+            For errors:
+            - message (str): Human-readable error description with guidance
+
+    Examples:
+        # Follow a user
+        update_bluesky_connection(
+            change_type="follow",
+            actor="alice.bsky.social"
+        )
+
+        # Unfollow a user
+        update_bluesky_connection(
+            change_type="unfollow",
+            actor="bob.bsky.social"
+        )
+
+        # Mute a user to hide their content without unfollowing
+        update_bluesky_connection(
+            change_type="mute",
+            actor="noisy.bsky.social"
+        )
+
+        # Unmute a previously muted user
+        update_bluesky_connection(
+            change_type="unmute",
+            actor="noisy.bsky.social"
+        )
+
+        # Block a user (strongest moderation action)
+        update_bluesky_connection(
+            change_type="block",
+            actor="spammer.bsky.social"
+        )
+
+        # Unblock a previously blocked user
+        update_bluesky_connection(
+            change_type="unblock",
+            actor="spammer.bsky.social"
+        )
+
+        # Use DID instead of handle
+        update_bluesky_connection(
+            change_type="follow",
+            actor="did:plc:z72i7hdynmk6r22z27h6tvur"
+        )
     """
     try:
-        from atproto import Client, models, AtUri
-
         if not actor:
-            raise ValueError("Actor identifier must be provided.")
+            return {
+                "status": "error",
+                "message": "Error: The actor parameter is empty. To resolve this, provide a valid user identifier "
+                           "such as a handle (like 'alice.bsky.social') or DID (like 'did:plc:...'). You can obtain "
+                           "user identifiers from tools like search_bluesky or get_bluesky_user_info. This is a common "
+                           "mistake and can be fixed by calling the tool again with a valid actor."
+            }
 
         if change_type not in ["follow", "unfollow", "mute", "unmute", "block", "unblock"]:
-            raise ValueError(f"Invalid change_type: {change_type}. Must be one of: follow, unfollow, mute, unmute, block, unblock.")
+            return {
+                "status": "error",
+                "message": f"Error: The change_type '{change_type}' is not valid. To resolve this, use one of the "
+                           f"supported values: 'follow', 'unfollow', 'mute', 'unmute', 'block', or 'unblock'. Each "
+                           f"type manages a different aspect of your connection with the user. This is a parameter "
+                           f"validation error that can be fixed by using a supported change type."
+            }
 
         username = os.environ.get("BSKY_USERNAME")
         password = os.environ.get("BSKY_APP_PASSWORD")
         if not username or not password:
-            raise EnvironmentError("BSKY_USERNAME and BSKY_APP_PASSWORD must be set.")
+            return {
+                "status": "error",
+                "message": "Error: Missing Bluesky authentication credentials. The BSKY_USERNAME and BSKY_APP_PASSWORD "
+                           "environment variables are not set. To resolve this, ask the user to configure these environment "
+                           "variables with valid Bluesky credentials. This is a configuration issue that the user needs to "
+                           "address before you can manage connections on Bluesky."
+            }
 
         client = Client()
         client.login(username, password)
 
-        # Get user profile to verify they exist and get current status
-        profile = client.get_profile(actor=actor)
+        # Get user profile to verify they exist, resolve handle to DID, and get current status
+        try:
+            profile = client.get_profile(actor=actor)
+        except Exception as e:
+            return {
+                "status": "error",
+                "message": f"Error: Failed to find user with identifier '{actor}'. To resolve this, verify the handle "
+                           f"or DID is correct and that the user exists. Common issues include typos in the handle, "
+                           f"deleted or suspended accounts, or using an incomplete handle (missing the domain like "
+                           f"'.bsky.social'). You can use search_bluesky to find valid user identifiers. "
+                           f"API details: {str(e)}"
+            }
+
+        # Extract DID for all operations (ensures we always use DID regardless of input format)
+        user_did = profile.did
 
         # Check current viewer state
         viewer = profile.viewer if profile.viewer else None
···
             }
         }
 
-        # Perform the requested action
+        # Perform the requested action (always using DID)
         if change_type == "follow":
             if viewer and viewer.following:
                 result["message"] = f"Already following {profile.handle}."
                 result["action_taken"] = False
             else:
-                client.follow(actor)
+                client.follow(user_did)
                 result["message"] = f"Successfully followed {profile.handle}."
                 result["action_taken"] = True
 
···
                 result["message"] = f"Already muted {profile.handle}."
                 result["action_taken"] = False
             else:
-                client.mute(actor)
+                client.mute(user_did)
                 result["message"] = f"Successfully muted {profile.handle}."
                 result["action_taken"] = True
 
         elif change_type == "unmute":
             if viewer and viewer.muted:
-                client.unmute(actor)
+                client.unmute(user_did)
                 result["message"] = f"Successfully unmuted {profile.handle}."
                 result["action_taken"] = True
             else:
···
                 result["message"] = f"Already blocked {profile.handle}."
                 result["action_taken"] = False
             else:
-                # Create block record with proper structure
+                # Create block record with proper structure (using resolved DID)
                 block_record = models.AppBskyGraphBlock.Record(
-                    subject=profile.did,
+                    subject=user_did,
                     created_at=client.get_current_time_iso()
                 )
                 client.app.bsky.graph.block.create(client.me.did, block_record)
···
         return result
 
     except ImportError:
-        raise ImportError("atproto package not installed. Install with: pip install atproto")
+        return {
+            "status": "error",
+            "message": "Error: The atproto Python package is not installed in the execution environment. "
+                       "To resolve this, the system administrator needs to install it using 'pip install atproto'. "
+                       "This is a dependency issue that prevents the tool from connecting to Bluesky. Once the "
+                       "package is installed, this tool will work normally."
+        }
     except Exception as e:
-        raise RuntimeError(f"Error updating Bluesky connection: {e}")
+        return {
+            "status": "error",
+            "message": f"Error: An unexpected issue occurred while updating the Bluesky connection: {str(e)}. "
+                       f"To resolve this, verify the actor identifier is correct and that the user exists. This type "
+                       f"of error can occur due to invalid actors, deleted accounts, temporary API issues, or network "
+                       f"problems, and usually succeeds on retry."
+        }