universal-mcp-applications 0.1.17__py3-none-any.whl → 0.1.33__py3-none-any.whl

universal_mcp/applications/reddit/README.md

@@ -9,127 +9,24 @@ This is automatically generated from OpenAPI schema for the RedditApp API.
 
 | Tool | Description |
 |------|-------------|
-| `get_subreddit_posts` | Retrieves and formats top posts from a specified subreddit within a given timeframe using the Reddit API |
-| `search_subreddits` | Searches Reddit for subreddits matching a given query string and returns a formatted list of results including subreddit names, subscriber counts, and descriptions. |
-| `get_post_flairs` | Retrieves a list of available post flairs for a specified subreddit using the Reddit API. |
-| `create_post` | Creates a new Reddit post in a specified subreddit with support for text posts, link posts, and image posts |
-| `get_comment_by_id` | Retrieves a specific Reddit comment using its unique identifier. |
-| `post_comment` | Posts a comment to a Reddit post or comment using the Reddit API |
-| `edit_content` | Edits the text content of an existing Reddit post or comment using the Reddit API |
-| `delete_content` | Deletes a specified Reddit post or comment using the Reddit API. |
-| `api_v1_me` | Get the current user's information. |
-| `api_v1_me_karma` | Get the current user's karma. |
-| `api_v1_me_prefs` | Get the current user's preferences. |
-| `api_v1_me_prefs1` | Update the current user's preferences. |
-| `api_v1_me_trophies` | Get the current user's trophies. |
-| `prefs_friends` | Get the current user's friends. |
-| `prefs_blocked` | Get the current user's blocked users. |
-| `prefs_messaging` | Get the current user's messaging preferences. |
-| `prefs_trusted` | Get the current user's trusted users. |
-| `api_needs_captcha` | Check if the current user needs a captcha. |
-| `api_v1_collections_collection` | Get a collection by ID. |
-| `api_v1_collections_subreddit_collections` | Get the current user's subreddit collections. |
-| `api_v1_subreddit_emoji_emoji_name` | Get an emoji by name. |
-| `api_v1_subreddit_emojis_all` | Get all emojis for a subreddit. |
-| `r_subreddit_api_flair` | Get the current user's flair for a subreddit. |
-| `r_subreddit_api_flairlist` | Get the current user's flair list for a subreddit. |
-| `r_subreddit_api_link_flair` | Get the current user's link flair for a subreddit. |
-| `r_subreddit_api_link_flair_v2` | Get the current user's link flair for a subreddit. |
-| `r_subreddit_api_user_flair` | Get the current user's user flair for a subreddit. |
-| `r_subreddit_api_user_flair_v2` | Get the current user's user flair for a subreddit. |
-| `api_info` | Get information about a link or comment. |
-| `r_subreddit_api_info` | Get information about a link or comment in a subreddit. |
-| `api_morechildren` | Get more children for a link or comment. |
-| `api_saved_categories` | Get the current user's saved categories. |
-| `req` | Get the current user's requests. |
-| `best` | Get the best posts. |
-| `by_id_names` | Get posts by ID. |
-| `comments_article` | Get comments for a post. |
-| `get_post_comments_details` | Get post details and comments like title, author, score, etc. |
-
-| `controversial` | Get the most controversial posts. |
-| `duplicates_article` | Get duplicate posts. |
-| `hot` | Get the hottest posts. |
-| `new` | Get the newest posts. |
-| `r_subreddit_comments_article` | Get comments for a post in a subreddit. |
-| `r_subreddit_controversial` | Get the most controversial posts in a subreddit. |
-| `r_subreddit_hot` | Get the hottest posts in a subreddit. |
-| `r_subreddit_new` | Get the newest posts in a subreddit. |
-| `r_subreddit_random` | Get a random post in a subreddit. |
-| `r_subreddit_rising` | Get the rising posts in a subreddit. |
-| `r_subreddit_top` | Get the top posts in a subreddit. |
-| `random` | Get a random post. |
-| `rising` | Get the rising posts. |
-| `top` | Get the top posts. |
-| `api_saved_media_text` | Get the text of a saved media. |
-| `api_v1_scopes` | Get the current user's scopes. |
-| `r_subreddit_api_saved_media_text` | Get the text of a saved media in a subreddit. |
-| `r_subreddit_about_log` | Get the log of a subreddit. |
-| `r_subreddit_about_edited` | Get the edited posts in a subreddit. |
-| `r_subreddit_about_modqueue` | Get the modqueue in a subreddit. |
-| `r_subreddit_about_reports` | Get the reports in a subreddit. |
-| `r_subreddit_about_spam` | Get the spam posts in a subreddit. |
-| `r_subreddit_about_unmoderated` | Get the unmoderated posts in a subreddit. |
-| `r_subreddit_stylesheet` | Get the stylesheet of a subreddit. |
-| `stylesheet` | Get the stylesheet of the current user. |
-| `api_mod_notes1` | Get the mod notes of a subreddit. |
-| `api_mod_notes` | Delete a mod note. |
-| `api_mod_notes_recent` | Get the recent mod notes. |
-| `api_multi_mine` | Get the current user's multi. |
-| `api_multi_user_username` | Get a user's multi. |
-| `api_multi_multipath1` | Get a multi. |
-| `api_multi_multipath` | Delete a multi. |
-| `api_multi_multipath_description` | Get a multi's description. |
-| `api_multi_multipath_rsubreddit1` | Get a multi's subreddit. |
-| `api_multi_multipath_rsubreddit` | Delete a multi's subreddit. |
-| `api_mod_conversations` | Get the mod conversations. |
-| `api_mod_conversations_conversation_id` | Get a mod conversation. |
-| `api_mod_conversations_conversation_id_highlight` | Highlight a mod conversation. |
-| `api_mod_conversations_conversation_id_unarchive` | Unarchive a mod conversation. |
-| `api_mod_conversations_conversation_id_unban` | Unban a mod conversation. |
-| `api_mod_conversations_conversation_id_unmute` | Unmute a mod conversation. |
-| `api_mod_conversations_conversation_id_user` | Get a mod conversation's user. |
-| `api_mod_conversations_subreddits` | Get the mod conversations' subreddits. |
-| `api_mod_conversations_unread_count` | Get the unread count of the mod conversations. |
-| `message_inbox` | Get the current user's inbox. |
-| `message_sent` | Get the current user's sent messages. |
-| `message_unread` | Get the current user's unread messages. |
-| `search` | Search for posts, comments, and users. |
-| `r_subreddit_search` | Search for posts, comments, and users in a subreddit. |
-| `api_search_reddit_names` | Search for subreddits. |
-| `api_subreddit_autocomplete` | Search for subreddits. |
-| `api_subreddit_autocomplete_v2` | Search for subreddits. |
-| `api_v1_subreddit_post_requirements` | Get the post requirements for a subreddit. |
-| `r_subreddit_about_banned` | Get the banned users in a subreddit. |
-| `r_subreddit_about` | Get the about information for a subreddit. |
-| `r_subreddit_about_edit` | Get the edit information for a subreddit. |
-| `r_subreddit_about_contributors` | Get the contributors for a subreddit. |
-| `r_subreddit_about_moderators` | Get the moderators for a subreddit. |
-| `r_subreddit_about_muted` | Get the muted users for a subreddit. |
-| `r_subreddit_about_rules` | Get the rules for a subreddit. |
-| `r_subreddit_about_sticky` | Get the sticky posts for a subreddit. |
-| `r_subreddit_about_traffic` | Get the traffic for a subreddit. |
-| `r_subreddit_about_wikibanned` | Get the wikibanned users for a subreddit. |
-| `r_subreddit_about_wikicontributors` | Get the wikicontributors for a subreddit. |
-| `r_subreddit_api_submit_text` | Get the submit text for a subreddit. |
-| `subreddits_mine_where` | Get the subreddits the current user has access to. |
-| `subreddits_search` | Search for subreddits. |
-| `subreddits_where` | Get the subreddits the current user has access to. |
-| `api_user_data_by_account_ids` | Get the user data by account IDs. |
-| `api_username_available` | Check if a username is available. |
-| `api_v1_me_friends_username1` | Get a user's friends. |
-| `api_v1_me_friends_username` | Delete a user's friend. |
-| `api_v1_user_username_trophies` | Get a user's trophies. |
-| `user_username_about` | Get the about information for a user. |
-| `user_username_where` | Get the user's posts or comments. |
-| `users_search` | Search for users. |
-| `users_where` | Get the user's posts or comments. |
-| `r_subreddit_api_widgets` | Get the widgets for a subreddit. |
-| `r_subreddit_api_widget_order_section` | Get the widget order for a subreddit. |
-| `r_subreddit_api_widget_widget_id` | Delete a widget. |
-| `r_subreddit_wiki_discussions_page` | Get the discussions for a wiki page. |
-| `r_subreddit_wiki_page` | Get a wiki page. |
-| `r_subreddit_wiki_pages` | Get the pages for a wiki. |
-| `r_subreddit_wiki_revisions` | Get the revisions for a wiki. |
-| `r_subreddit_wiki_revisions_page` | Get the revisions for a wiki page. |
-| `r_subreddit_wiki_settings_page` | Get the settings for a wiki page. |
+| `get_subreddit_posts` | Fetches a specified number of top-rated posts from a particular subreddit, allowing results to be filtered by a specific timeframe (e.g., 'day', 'week'). This is a simplified version compared to `get_subreddit_top_posts`, which uses more complex pagination parameters instead of a direct time filter. |
+| `search_subreddits` | Searches for subreddits by name and description using a query string, with results sortable by relevance or activity. Unlike the broader `search_reddit` function, this method exclusively discovers subreddits, not posts, comments, or users. |
+| `get_post_flairs` | Fetches a list of available post flairs (tags) for a specified subreddit. This is primarily used to discover the correct `flair_id` needed to categorize a new submission when using the `create_post` function. It returns flair details or a message if none are available. |
+| `create_post` | Creates a new Reddit post in a specified subreddit. It supports text ('self') or link posts, requiring a title and corresponding content (text or URL). An optional flair can be assigned. Returns the API response or a formatted error message on failure. |
+| `get_comment_by_id` | Retrieves a single Reddit comment's data, such as author and score, using its unique 't1_' prefixed ID. Unlike `get_post_comments_details` which fetches all comments for a post, this function targets one specific comment directly, returning an error dictionary if it is not found. |
+| `post_comment` | Posts a new comment as a reply to a specified Reddit post or another comment. Using the parent's full ID and the desired text, it submits the comment via the API and returns the response containing the new comment's details. |
+| `edit_content` | Modifies the text of a specific Reddit post or comment via its unique ID. Unlike creation or deletion functions, this method specifically handles updates to existing user-generated content, submitting the new text to the API and returning a JSON response detailing the edited item. |
+| `delete_content` | Deletes a specified Reddit post or comment using its full identifier (`content_id`). It sends a POST request to the `/api/del` endpoint for permanent removal, unlike `edit_content` which only modifies. On success, it returns a confirmation message. |
+| `get_post_comments_details` | Fetches a specific Reddit post's details and its complete comment tree using the post's unique ID. This function returns the entire discussion, including the original post and all associated comments, providing broader context than `get_comment_by_id` which only retrieves a single comment. |
+| `get_current_user_info` | Retrieves the full profile information for the currently authenticated user by making a GET request to the `/api/v1/me` Reddit API endpoint. This differs from `get_user_profile`, which requires a username, and `get_current_user_karma`, which specifically fetches karma data. |
+| `get_current_user_karma` | Fetches the karma breakdown for the authenticated user from the Reddit API. This function specifically targets the `/api/v1/me/karma` endpoint, returning karma statistics per subreddit, which is more specific than `get_current_user_info` that retrieves general profile information. |
+| `get_hot_posts` | Retrieves trending 'hot' posts from the global Reddit feed. Unlike `get_subreddit_hot_posts`, this operates across all of Reddit, not a specific subreddit. It supports pagination and optional filtering by geographical region to customize the listing of returned posts. |
+| `get_new_posts` | Fetches a list of the newest posts from across all of Reddit, not limited to a specific subreddit. This function supports optional pagination and filtering parameters to customize the API response, differentiating it from `get_subreddit_new_posts` which targets a single subreddit. |
+| `get_top_posts` | Fetches top-rated posts from across all of Reddit, distinct from `get_subreddit_top_posts`, which operates on a specific subreddit. The function supports standard API pagination parameters like `limit`, `after`, and `before` to navigate results, providing a broad, site-wide view of top content. |
+| `get_rising_posts` | Retrieves a list of rising posts from across all of Reddit. Unlike subreddit-specific listing functions (e.g., `get_subreddit_hot_posts`), this operates globally. It supports optional pagination and filtering parameters, such as `limit` and `after`, to customize the API response and navigate through results. |
+| `get_controversial_posts` | Fetches a global list of the most controversial posts from across all of Reddit, distinct from subreddit-specific queries. Optional parameters allow for pagination and customization of the results, returning the direct API response data with the post listings. |
+| `get_subreddit_hot_posts` | Retrieves a list of 'hot' posts from a specified subreddit, supporting pagination and geographical filtering. Unlike `get_hot_posts`, which queries all of Reddit, this function targets a single subreddit to fetch its currently trending content, distinct from top or new posts. |
+| `get_subreddit_new_posts` | Retrieves a list of the newest posts from a specified subreddit, sorted chronologically. Unlike `get_new_posts` which targets all of Reddit, this function is subreddit-specific and supports standard pagination parameters like `limit` and `after` to navigate through the listing of recent submissions. |
+| `get_subreddit_top_posts` | Fetches top-rated posts from a specific subreddit using standard API pagination parameters. Unlike the simpler `get_subreddit_posts` which filters by timeframe, this function offers more direct control over retrieving listings, distinguishing it from the site-wide `get_top_posts` which queries all of Reddit. |
+| `search_reddit` | Executes a broad, keyword-based search across Reddit for various content types like posts, comments, or users. This general-purpose function offers extensive filtering options, distinguishing it from the more specialized `search_subreddits` which only finds communities. |
+| `get_user_profile` | Retrieves public profile information for a specified Reddit user via the `/user/{username}/about` endpoint. Unlike `get_current_user_info`, which targets the authenticated user, this function fetches data like karma and account age for any user identified by their username. |

universal_mcp/applications/reddit/app.py

@@ -2,7 +2,6 @@ from typing import Any
 
 import httpx
 from loguru import logger
-
 from universal_mcp.applications.application import APIApplication
 from universal_mcp.exceptions import NotAuthorizedError
 from universal_mcp.integrations import Integration
@@ -45,11 +44,9 @@ class RedditApp(APIApplication):
             "User-Agent": "agentr-reddit-app/0.1 by AgentR",
         }
 
-    def get_subreddit_posts(
-        self, subreddit: str, limit: int = 5, timeframe: str = "day"
-    ) -> dict[str, Any]:
+    def get_subreddit_posts(self, subreddit: str, limit: int = 5, timeframe: str = "day") -> dict[str, Any]:
         """
-        Fetches top posts from a given subreddit, filterable by time.
+        Fetches a specified number of top-rated posts from a particular subreddit, allowing results to be filtered by a specific timeframe (e.g., 'day', 'week'). This is a simplified version compared to `get_subreddit_top_posts`, which uses more complex pagination parameters instead of a direct time filter.
 
         Args:
             subreddit: The name of the subreddit (e.g., 'python', 'worldnews') without the 'r/' prefix
@@ -57,7 +54,7 @@ class RedditApp(APIApplication):
             timeframe: The time period for top posts. Valid options: 'hour', 'day', 'week', 'month', 'year', 'all' (default: 'day')
 
         Returns:
-            A formatted string containing a numbered list of top posts, including titles, authors, scores, and URLs, or an error message if the request fails
+            A dictionary containing a list of top posts with their details, or an error message if the request fails.
 
         Raises:
             RequestException: When the HTTP request to the Reddit API fails
@@ -70,34 +67,29 @@ class RedditApp(APIApplication):
         if timeframe not in valid_timeframes:
             return f"Error: Invalid timeframe '{timeframe}'. Please use one of: {', '.join(valid_timeframes)}"
         if not 1 <= limit <= 100:
-            return (
-                f"Error: Invalid limit '{limit}'. Please use a value between 1 and 100."
-            )
+            return f"Error: Invalid limit '{limit}'. Please use a value between 1 and 100."
         url = f"{self.base_api_url}/r/{subreddit}/top"
         params = {"limit": limit, "t": timeframe}
-        logger.info(
-            f"Requesting top {limit} posts from r/{subreddit} for timeframe '{timeframe}'"
-        )
+        logger.info(f"Requesting top {limit} posts from r/{subreddit} for timeframe '{timeframe}'")
         response = self._get(url, params=params)
         return self._handle_response(response)
 
-    def search_subreddits(
-        self, query: str, limit: int = 5, sort: str = "relevance"
-    ) -> str:
+    def search_subreddits(self, query: str, limit: int = 5, sort: str = "relevance") -> dict[str, Any]:
         """
-        Searches Reddit for subreddits matching a given query string and returns a formatted list of results including subreddit names, subscriber counts, and descriptions.
+        Finds subreddits based on a query string, searching their names and descriptions.
+        Results can be sorted by relevance or activity. This function is for discovering communities and does not search for posts or users, unlike the more general `search_reddit` function.
 
         Args:
-            query: The text to search for in subreddit names and descriptions
-            limit: The maximum number of subreddits to return, between 1 and 100 (default: 5)
-            sort: The order of results, either 'relevance' or 'activity' (default: 'relevance')
+            query: The search query for subreddit names and descriptions.
+            limit: The maximum number of subreddits to return (1-100, default is 5).
+            sort: The sorting order for results. Can be 'relevance' or 'activity' (default is 'relevance').
 
         Returns:
-            A formatted string containing a list of matching subreddits with their names, subscriber counts, and descriptions, or an error message if the search fails or parameters are invalid
+            A dictionary containing a list of matching subreddits, including their names, subscriber counts, and descriptions. Returns an error message on failure.
 
         Raises:
-            RequestException: When the HTTP request to Reddit's API fails
-            JSONDecodeError: When the API response contains invalid JSON
+            RequestException: If the API request to Reddit fails.
+            JSONDecodeError: If the API response is not valid JSON.
 
         Tags:
             search, important, reddit, api, query, format, list, validation
@@ -106,24 +98,20 @@ class RedditApp(APIApplication):
         if sort not in valid_sorts:
             return f"Error: Invalid sort option '{sort}'. Please use one of: {', '.join(valid_sorts)}"
         if not 1 <= limit <= 100:
-            return (
-                f"Error: Invalid limit '{limit}'. Please use a value between 1 and 100."
-            )
+            return f"Error: Invalid limit '{limit}'. Please use a value between 1 and 100."
         url = f"{self.base_api_url}/subreddits/search"
         params = {
             "q": query,
             "limit": limit,
             "sort": sort,
         }
-        logger.info(
-            f"Searching for subreddits matching '{query}' (limit: {limit}, sort: {sort})"
-        )
+        logger.info(f"Searching for subreddits matching '{query}' (limit: {limit}, sort: {sort})")
         response = self._get(url, params=params)
         return self._handle_response(response)
 
     def get_post_flairs(self, subreddit: str):
         """
-        Retrieves a list of available post flairs for a specified subreddit using the Reddit API.
+        Fetches a list of available post flairs (tags) for a specified subreddit. This is primarily used to discover the correct `flair_id` needed to categorize a new submission when using the `create_post` function. It returns flair details or a message if none are available.
 
         Args:
             subreddit: The name of the subreddit (e.g., 'python', 'worldnews') without the 'r/' prefix
@@ -156,7 +144,7 @@ class RedditApp(APIApplication):
         flair_id: str = None,
     ):
         """
-        Creates a new Reddit post in a specified subreddit with support for text posts, link posts, and image posts
+        Creates a new Reddit post in a specified subreddit. It supports text ('self') or link posts, requiring a title and corresponding content (text or URL). An optional flair can be assigned. Returns the API response or a formatted error message on failure.
 
         Args:
             subreddit: The name of the subreddit (e.g., 'python', 'worldnews') without the 'r/'
@@ -194,22 +182,16 @@ class RedditApp(APIApplication):
         logger.info(f"Submitting a new post to r/{subreddit}")
         response = self._post(url_api, data=data)
         response_json = response.json()
-        if (
-            response_json
-            and "json" in response_json
-            and "errors" in response_json["json"]
-        ):
+        if response_json and "json" in response_json and "errors" in response_json["json"]:
             errors = response_json["json"]["errors"]
             if errors:
-                error_message = ", ".join(
-                    [f"{code}: {message}" for code, message in errors]
-                )
+                error_message = ", ".join([f"{code}: {message}" for code, message in errors])
                 return f"Reddit API error: {error_message}"
         return response_json
 
     def get_comment_by_id(self, comment_id: str) -> dict:
         """
-        Retrieves a specific Reddit comment using its unique identifier.
+        Retrieves a single Reddit comment's data, such as author and score, using its unique 't1_' prefixed ID. Unlike `get_post_comments_details` which fetches all comments for a post, this function targets one specific comment directly, returning an error dictionary if it is not found.
 
         Args:
             comment_id: The full unique identifier of the comment (prefixed with 't1_', e.g., 't1_abcdef')
@@ -235,7 +217,7 @@ class RedditApp(APIApplication):
 
     def post_comment(self, parent_id: str, text: str) -> dict:
         """
-        Posts a comment to a Reddit post or comment using the Reddit API
+        Posts a new comment as a reply to a specified Reddit post or another comment. Using the parent's full ID and the desired text, it submits the comment via the API and returns the response containing the new comment's details.
 
         Args:
             parent_id: The full ID of the parent comment or post (e.g., 't3_abc123' for a post, 't1_def456' for a comment)
@@ -262,7 +244,7 @@ class RedditApp(APIApplication):
 
     def edit_content(self, content_id: str, text: str) -> dict:
         """
-        Edits the text content of an existing Reddit post or comment using the Reddit API
+        Modifies the text of a specific Reddit post or comment via its unique ID. Unlike creation or deletion functions, this method specifically handles updates to existing user-generated content, submitting the new text to the API and returning a JSON response detailing the edited item.
 
         Args:
             content_id: The full ID of the content to edit (e.g., 't3_abc123' for a post, 't1_def456' for a comment)
@@ -289,7 +271,7 @@ class RedditApp(APIApplication):
 
     def delete_content(self, content_id: str) -> dict:
         """
-        Deletes a specified Reddit post or comment using the Reddit API.
+        Deletes a specified Reddit post or comment using its full identifier (`content_id`). It sends a POST request to the `/api/del` endpoint for permanent removal, unlike `edit_content` which only modifies. On success, it returns a confirmation message.
 
         Args:
             content_id: The full ID of the content to delete (e.g., 't3_abc123' for a post, 't1_def456' for a comment)
@@ -315,9 +297,10 @@ class RedditApp(APIApplication):
 
     def get_current_user_info(self) -> Any:
         """
-        Get the current user's information.
+        Retrieves the full profile information for the currently authenticated user by making a GET request to the `/api/v1/me` Reddit API endpoint. This differs from `get_user_profile`, which requires a username, and `get_current_user_karma`, which specifically fetches karma data.
+
         Returns:
-            Any: API response data.
+            A dictionary containing the authenticated user's profile information.
 
         Tags:
             users
@@ -330,10 +313,10 @@ class RedditApp(APIApplication):
 
     def get_current_user_karma(self) -> Any:
         """
-        Get the current user's karma.
+        Fetches the karma breakdown for the authenticated user from the Reddit API. This function specifically targets the `/api/v1/me/karma` endpoint, returning karma statistics per subreddit, which is more specific than `get_current_user_info` that retrieves general profile information.
 
         Returns:
-            Any: API response data.
+            A dictionary containing the authenticated user's karma breakdown by subreddit.
 
         Tags:
             account
@@ -346,13 +329,13 @@ class RedditApp(APIApplication):
 
     def get_post_comments_details(self, post_id: str) -> Any:
         """
-        Get post details and comments like title, author, score, etc.
+        Fetches a specific Reddit post's details and its complete comment tree using the post's unique ID. This function returns the entire discussion, including the original post and all associated comments, providing broader context than `get_comment_by_id` which only retrieves a single comment.
 
         Args:
-            post_id (string): The Reddit post ID ( e.g. '1m734tx' for https://www.reddit.com/r/mcp/comments/1m734tx/comment/n4occ77/)
+            post_id (str): The Reddit post ID ( e.g. '1m734tx' for https://www.reddit.com/r/mcp/comments/1m734tx/comment/n4occ77/)
 
         Returns:
-            Any: API response data containing post details and comments.
+            A dictionary containing the post details and its comment tree.
 
         Tags:
             listings, comments, posts, important
@@ -373,7 +356,7 @@ class RedditApp(APIApplication):
         sr_detail: str = None,
     ) -> Any:
         """
-        Retrieves a list of the most controversial posts across Reddit.
+        Fetches a global list of the most controversial posts from across all of Reddit, distinct from subreddit-specific queries. Optional parameters allow for pagination and customization of the results, returning the direct API response data with the post listings.
 
         Args:
             after: Optional. The fullname of a thing (e.g., 't3_xxxxxx') to return results after.
@@ -384,7 +367,7 @@ class RedditApp(APIApplication):
             sr_detail: Optional. Expand subreddit details.
 
         Returns:
-            Any: API response data containing a list of controversial posts.
+            A dictionary containing a listing of controversial posts.
 
         Tags:
             listings, posts, controversial, read-only
@@ -417,7 +400,7 @@ class RedditApp(APIApplication):
         sr_detail: str = None,
     ) -> Any:
         """
-        Retrieves a list of the hottest posts across Reddit.
+        Retrieves trending 'hot' posts from the global Reddit feed. Unlike `get_subreddit_hot_posts`, this operates across all of Reddit, not a specific subreddit. It supports pagination and optional filtering by geographical region to customize the listing of returned posts.
 
         Args:
             g: Optional. A geographical region to filter posts by (e.g., 'GLOBAL', 'US', 'GB').
@@ -429,7 +412,7 @@ class RedditApp(APIApplication):
             sr_detail: Optional. Expand subreddit details.
 
         Returns:
-            Any: API response data containing a list of hot posts.
+            A dictionary containing a listing of hot posts.
 
         Tags:
             listings, posts, hot, read-only
@@ -462,7 +445,7 @@ class RedditApp(APIApplication):
         sr_detail: str = None,
     ) -> Any:
         """
-        Retrieves a list of the newest posts across Reddit.
+        Fetches a list of the newest posts from across all of Reddit, not limited to a specific subreddit. This function supports optional pagination and filtering parameters to customize the API response, differentiating it from `get_subreddit_new_posts` which targets a single subreddit.
 
         Args:
             after: Optional. The fullname of a thing (e.g., 't3_xxxxxx') to return results after.
@@ -473,7 +456,7 @@ class RedditApp(APIApplication):
             sr_detail: Optional. Expand subreddit details.
 
         Returns:
-            Any: API response data containing a list of new posts.
+            A dictionary containing a listing of new posts.
 
         Tags:
             listings, posts, new, read-only
@@ -507,7 +490,7 @@ class RedditApp(APIApplication):
         sr_detail: str = None,
     ) -> Any:
         """
-        Retrieves a list of the hottest posts in a specified subreddit.
+        Retrieves a list of 'hot' posts from a specified subreddit, supporting pagination and geographical filtering. Unlike `get_hot_posts`, which queries all of Reddit, this function targets a single subreddit to fetch its currently trending content, distinct from top or new posts.
 
         Args:
             subreddit: The name of the subreddit (e.g., 'python', 'worldnews') without the 'r/' prefix.
@@ -520,7 +503,7 @@ class RedditApp(APIApplication):
             sr_detail: Optional. Expand subreddit details.
 
         Returns:
-            Any: API response data containing a list of hot posts from the subreddit.
+            A dictionary containing a listing of hot posts from the specified subreddit.
 
         Tags:
             listings, posts, subreddit, hot, read-only
@@ -556,7 +539,7 @@ class RedditApp(APIApplication):
         sr_detail: str = None,
     ) -> Any:
         """
-        Retrieves a list of the newest posts in a specified subreddit.
+        Retrieves a list of the newest posts from a specified subreddit, sorted chronologically. Unlike `get_new_posts` which targets all of Reddit, this function is subreddit-specific and supports standard pagination parameters like `limit` and `after` to navigate through the listing of recent submissions.
 
         Args:
             subreddit: The name of the subreddit (e.g., 'python', 'worldnews') without the 'r/' prefix.
@@ -568,7 +551,7 @@ class RedditApp(APIApplication):
             sr_detail: Optional. Expand subreddit details.
 
         Returns:
-            Any: API response data containing a list of new posts from the subreddit.
+            A dictionary containing a listing of new posts from the specified subreddit.
 
         Tags:
             listings, posts, subreddit, new, read-only
@@ -603,7 +586,7 @@ class RedditApp(APIApplication):
         sr_detail: str = None,
     ) -> Any:
         """
-        Retrieves a list of the top posts in a specified subreddit.
+        Fetches top-rated posts from a specific subreddit using standard API pagination parameters. Unlike the simpler `get_subreddit_posts` which filters by timeframe, this function offers more direct control over retrieving listings, distinguishing it from the site-wide `get_top_posts` which queries all of Reddit.
 
         Args:
             subreddit: The name of the subreddit (e.g., 'python', 'worldnews') without the 'r/' prefix.
@@ -615,7 +598,7 @@ class RedditApp(APIApplication):
             sr_detail: Optional. Expand subreddit details.
 
         Returns:
-            Any: API response data containing a list of top posts from the subreddit.
+            A dictionary containing a listing of top posts from the specified subreddit.
 
         Tags:
             listings, posts, subreddit, top, read-only
@@ -649,7 +632,7 @@ class RedditApp(APIApplication):
         sr_detail: str = None,
     ) -> Any:
         """
-        Retrieves a list of the rising posts across Reddit.
+        Retrieves a list of rising posts from across all of Reddit. Unlike subreddit-specific listing functions (e.g., `get_subreddit_hot_posts`), this operates globally. It supports optional pagination and filtering parameters, such as `limit` and `after`, to customize the API response and navigate through results.
 
         Args:
             after: Optional. The fullname of a thing (e.g., 't3_xxxxxx') to return results after.
@@ -660,7 +643,7 @@ class RedditApp(APIApplication):
             sr_detail: Optional. Expand subreddit details.
 
         Returns:
-            Any: API response data containing a list of rising posts.
+            A dictionary containing a listing of rising posts.
 
         Tags:
             listings, posts, rising, read-only
@@ -692,7 +675,7 @@ class RedditApp(APIApplication):
         sr_detail: str = None,
     ) -> Any:
         """
-        Retrieves a list of the top posts across Reddit.
+        Fetches top-rated posts from across all of Reddit, distinct from `get_subreddit_top_posts`, which operates on a specific subreddit. The function supports standard API pagination parameters like `limit`, `after`, and `before` to navigate results, providing a broad, site-wide view of top content.
 
         Args:
             after: Optional. The fullname of a thing (e.g., 't3_xxxxxx') to return results after.
@@ -703,7 +686,7 @@ class RedditApp(APIApplication):
             sr_detail: Optional. Expand subreddit details.
 
         Returns:
-            Any: API response data containing a list of top posts.
+            A dictionary containing a listing of top posts.
 
         Tags:
             listings, posts, top, read-only
@@ -742,7 +725,7 @@ class RedditApp(APIApplication):
         type: str = None,
     ) -> Any:
         """
-        Searches for posts, comments, and users across Reddit.
+        Executes a broad, keyword-based search across Reddit for various content types like posts, comments, or users. This general-purpose function offers extensive filtering options, distinguishing it from the more specialized `search_subreddits` which only finds communities.
 
         Args:
             after: Optional. The fullname of a thing (e.g., 't3_xxxxxx') to return results after.
@@ -760,7 +743,7 @@ class RedditApp(APIApplication):
             type: Optional. A comma-separated list of result types ('sr', 'link', 'user').
 
         Returns:
-            Any: API response data containing search results.
+            A dictionary containing the search results.
 
         Tags:
             search, reddit, posts, comments, users, read-only
@@ -791,7 +774,7 @@ class RedditApp(APIApplication):
 
     def get_user_profile(self, username: str) -> Any:
         """
-        Retrieves the profile information for a given Reddit user.
+        Retrieves public profile information for a specified Reddit user via the `/user/{username}/about` endpoint. Unlike `get_current_user_info`, which targets the authenticated user, this function fetches data like karma and account age for any user identified by their username.
 
         Args:
             username: The username of the user to look up.

universal_mcp/applications/resend/README.md

@@ -9,32 +9,32 @@ This is automatically generated from OpenAPI schema for the ResendApp API.
 
 | Tool | Description |
 |------|-------------|
-| `send_email` | Sends an email to specified recipients using the Resend API. |
-| `send_batch_emails` | Sends a batch of emails using the Resend API. |
-| `get_email` | Retrieves a single email by its specified ID. |
-| `update_scheduled_email` | Updates the scheduling of an email to a new time. |
-| `cancel_scheduled_email` | Cancels a scheduled email using the provided email ID. |
-| `create_domain` | Creates a new domain with the specified name. |
-| `get_domain` | Retrieves a single domain by its ID. |
-| `verify_domain` | Verifies an existing domain using the provided domain ID. |
-| `update_domain` | Updates an existing domain's settings regarding open tracking, click tracking, and TLS enforcement. |
-| `list_domains` | Retrieves a list of all domains for the authenticated user. |
-| `remove_domain` | Removes an existing domain by its ID using the Resend API. |
-| `create_api_key` | Creates a new API key for authenticating with Resend. |
-| `list_api_keys` | Retrieves a list of all API keys available through the resend service. |
-| `remove_api_key` | Removes an existing API key using the specified key ID. |
-| `create_broadcast` | Creates a new broadcast to send to a specified audience. |
-| `get_broadcast` | Retrieves a single broadcast by its ID. |
-| `update_broadcast` | Updates a broadcast by modifying its HTML content and/or subject line. |
-| `send_broadcast` | Starts sending a broadcast via the API. |
-| `remove_broadcast` | Removes an existing broadcast with 'draft' status. |
-| `list_broadcasts` | Retrieves a list of all available broadcasts using the configured API key. |
-| `create_audience` | Creates a new audience (a list of contacts) with the specified name. |
-| `get_audience` | Retrieves a single audience object from the API using the specified audience ID. |
-| `remove_audience` | Removes an existing audience using the provided audience ID and returns the API response. |
-| `list_audiences` | Retrieves a list of all audiences. |
-| `create_contact` | Creates a contact within a specific audience. |
-| `get_contact` | Retrieves a single contact from an audience by providing either a unique contact ID or an email address, ensuring exactly one identifier is given. |
-| `update_contact` | Updates an existing contact, identified by ID or email, within a specified audience. |
-| `remove_contact` | Removes a contact from an audience, identified by ID or email. |
-| `list_contacts` | Lists all contacts from a specified audience. |
+| `send_email` | Sends a single email with a specified subject and text body to a list of recipients via the Resend API. Unlike `send_batch_emails`, which processes multiple distinct emails at once, this function is designed for dispatching one individual email composition per API call. |
+| `send_batch_emails` | Sends multiple emails (1-100) in a single API request. Unlike the `send_email` function which handles a single message, this accepts a list of email objects for efficient, high-volume delivery. It validates that the batch size is within the allowed limits before making the API call. |
+| `retrieve_email_by_id` | Retrieves the details and status of a single email from the Resend API using its unique identifier. This function allows for looking up a specific email that has already been sent or scheduled, distinct from functions that initiate sending. |
+| `reschedule_email` | Modifies the delivery time for a specific, previously scheduled email using its ID. It updates the `scheduled_at` attribute to a new ISO 8601 formatted time, effectively rescheduling its dispatch. This differs from `cancel_scheduled_email`, which permanently stops the send. |
+| `cancel_scheduled_email` | Cancels a previously scheduled email using its unique ID, preventing it from being sent. This function calls the Resend API's cancellation endpoint, returning a confirmation response. It is distinct from `update_scheduled_email`, which reschedules the email instead of stopping its transmission. |
+| `create_domain` | Registers a new sending domain with the Resend service using the provided name. This is a prerequisite for sending emails from your own domain and returns a dictionary containing details of the new domain object, which can then be verified and managed with other domain-related functions. |
+| `get_domain` | Retrieves the details of a specific domain from the Resend API using its unique ID. Unlike `list_domains`, which fetches all domains, this function targets a single record and returns a dictionary containing the domain's properties, like its verification status and tracking settings. |
+| `verify_domain` | Triggers the verification process for a registered domain using its unique ID. This action is crucial for authorizing the domain to send emails via Resend and returns an API response containing the verification status and necessary DNS records to complete the process. |
+| `update_domain_settings` | Updates settings for a specific domain identified by its ID. This function can modify configurations like open and click tracking, and TLS enforcement. It returns the updated domain object from the API, raising a ToolError if the update fails. Only the provided settings are modified. |
+| `list_domains` | Fetches a complete list of all domains registered with the Resend account. Unlike `get_domain`, which retrieves a single domain by ID, this provides a comprehensive overview of all configured domains for management and verification tasks. |
+| `remove_domain` | Permanently removes a specific domain from the Resend account using its unique ID. This function makes an authenticated API call to delete the domain, distinguishing it from retrieval (`get_domain`) or modification (`update_domain`) operations, and raises an error if the process fails. |
+| `create_api_key` | Creates a new API key for authenticating with the Resend service, identified by a specified name. It returns a dictionary containing the new key object, including the generated token required for subsequent API requests. |
+| `list_api_keys` | Retrieves a list of all API keys for the authenticated Resend account. This read-only operation allows for auditing and viewing existing credentials, contrasting with `create_api_key` and `remove_api_key` which are used to add or delete keys. |
+| `remove_api_key` | Deletes a specific Resend API key identified by its unique ID. This function, part of the key management suite alongside `create_api_key` and `list_api_keys`, returns an API confirmation response or raises a `ToolError` if the operation fails. |
+| `register_broadcast` | Registers a new email broadcast campaign for a specific audience using the Resend API. This function creates the broadcast object but does not send it; use the `send_broadcast` function to dispatch the created campaign to the audience. |
+| `get_broadcast` | Retrieves a specific broadcast's complete details, including its status and content, by its unique ID. Unlike `list_broadcasts` which retrieves all broadcasts, this function targets a single entry for inspection. |
+| `update_broadcast` | Updates the HTML content and/or subject of an existing broadcast, identified by its ID. Requires that at least one modifiable field (html or subject) is provided. This function alters a broadcast's content, differing from `send_broadcast` which triggers its delivery. |
+| `send_or_schedule_broadcast` | Initiates the delivery of a pre-existing broadcast, identified by its ID, to its target audience. The broadcast can be sent immediately or scheduled for a future time via the optional `scheduled_at` parameter. It returns the API response upon execution. |
+| `remove_draft_broadcast` | Deletes a broadcast from the Resend service using its unique ID. This action is restricted to broadcasts that have a 'draft' status and have not been sent, returning the API's response upon successful removal or raising an error if the operation fails. |
+| `list_broadcasts` | Retrieves a list of all broadcasts associated with the authenticated account. Unlike `get_broadcast` which fetches a single item by ID, this function returns a list of dictionaries, each containing the attributes of a specific broadcast. Raises a `ToolError` on API failure. |
+| `create_audience` | Creates a new audience, a named list for contacts, within the Resend service. This function requires a name for the audience and returns a dictionary representing the newly created object, enabling subsequent management of contacts within that specific list. |
+| `get_audience` | Retrieves the details of a single audience using its unique ID. This provides a targeted lookup for one audience, distinct from `list_audiences` which fetches all available audiences in the account. |
+| `remove_audience` | Deletes a specific audience from the Resend service using its unique identifier. This function wraps the Resend API's remove operation, returning the API's response. Unlike `remove_contact`, which targets individuals, this function removes the entire contact list defined by the audience ID. |
+| `list_audiences` | Retrieves a complete list of all audiences from the Resend account. It returns a list of dictionaries, with each containing the details of a specific audience. This function is distinct from `get_audience`, which fetches a single audience by its ID. |
+| `create_contact` | Creates a new contact with a given email, optional name, and subscription status, adding it to a specific audience. This function populates audience lists, differing from `update_contact` which modifies existing entries, and requires a valid `audience_id` to function. |
+| `get_contact` | Fetches a single contact's details from a specified audience by its unique ID or email address. The function requires exactly one identifier for the lookup, raising an error if the identifier is missing, ambiguous, or if the API call fails. |
+| `update_contact` | Updates an existing contact's details (e.g., name, subscription status) within a specific audience. The contact is identified by its unique ID or email address. This function validates inputs and returns the Resend API response, raising a ToolError on failure or if arguments are invalid. |
+| `remove_contact` | Removes a contact from a specified audience. The contact must be identified by either its unique ID or email address, but not both. Raises an error if the identifier is missing, ambiguous, or if the API call to the Resend service fails. |
+| `list_contacts` | Retrieves a complete list of contacts belonging to a specific audience, identified by its unique ID. This function returns all contacts within the audience, unlike `get_contact` which retrieves only a single contact by its ID or email. |