docstrings `tools` (#7848)

Added docstrings in `tools`.

 @baskaryan

langchain/tools/arxiv/tool.py

@@ -13,7 +13,7 @@ from langchain.utilities.arxiv import ArxivAPIWrapper
 
 
 class ArxivQueryRun(BaseTool):
-    """Tool that adds the capability to search using the Arxiv API."""
+    """Tool that searches the Arxiv API."""
 
     name = "arxiv"
     description = (

langchain/tools/bing_search/tool.py

@@ -11,7 +11,7 @@ from langchain.utilities.bing_search import BingSearchAPIWrapper
 
 
 class BingSearchRun(BaseTool):
-    """Tool that adds the capability to query the Bing search API."""
+    """Tool that queries the Bing search API."""
 
     name = "bing_search"
     description = (
@@ -39,7 +39,7 @@ class BingSearchRun(BaseTool):
 
 
 class BingSearchResults(BaseTool):
-    """Tool that has capability to query the Bing Search API and get back json."""
+    """Tool that queries the Bing Search API and gets back json."""
 
     name = "Bing Search Results JSON"
     description = (

langchain/tools/brave_search/tool.py

@@ -11,6 +11,8 @@ from langchain.utilities.brave_search import BraveSearchWrapper
 
 
 class BraveSearch(BaseTool):
+    """Tool that queries the BraveSearch."""
+
     name = "brave_search"
     description = (
         "a search engine. "
@@ -23,6 +25,16 @@ class BraveSearch(BaseTool):
     def from_api_key(
         cls, api_key: str, search_kwargs: Optional[dict] = None, **kwargs: Any
     ) -> BraveSearch:
+        """Create a tool from an api key.
+
+        Args:
+            api_key: The api key to use.
+            search_kwargs: Any additional kwargs to pass to the search wrapper.
+            **kwargs: Any additional kwargs to pass to the tool.
+
+        Returns:
+            A tool.
+        """
         wrapper = BraveSearchWrapper(api_key=api_key, search_kwargs=search_kwargs or {})
         return cls(search_wrapper=wrapper, **kwargs)
 

langchain/tools/dataforseo_api_search/tool.py

@@ -13,7 +13,7 @@ from langchain.utilities.dataforseo_api_search import DataForSeoAPIWrapper
 
 
 class DataForSeoAPISearchRun(BaseTool):
-    """Tool that adds the capability to query the DataForSeo Google search API."""
+    """Tool that queries the DataForSeo Google search API."""
 
     name = "dataforseo_api_search"
     description = (
@@ -41,7 +41,7 @@ class DataForSeoAPISearchRun(BaseTool):
 
 
 class DataForSeoAPISearchResults(BaseTool):
-    """Tool that has capability to query the DataForSeo Google Search API
+    """Tool that queries the DataForSeo Google Search API
     and get back json."""
 
     name = "DataForSeo Results JSON"

langchain/tools/ddg_search/tool.py

@@ -14,7 +14,7 @@ from langchain.utilities.duckduckgo_search import DuckDuckGoSearchAPIWrapper
 
 
 class DuckDuckGoSearchRun(BaseTool):
-    """Tool that adds the capability to query the DuckDuckGo search API."""
+    """Tool that queries the DuckDuckGo search API."""
 
     name = "duckduckgo_search"
     description = (
@@ -44,7 +44,7 @@ class DuckDuckGoSearchRun(BaseTool):
 
 
 class DuckDuckGoSearchResults(BaseTool):
-    """Tool that queries the DuckDuckGo search API and get back json."""
+    """Tool that queries the DuckDuckGo search API and gets back json."""
 
     name = "DuckDuckGo Results JSON"
     description = (

langchain/tools/file_management/copy.py

@@ -23,6 +23,8 @@ class FileCopyInput(BaseModel):
 
 
 class CopyFileTool(BaseFileToolMixin, BaseTool):
+    """Tool that copies a file."""
+
     name: str = "copy_file"
     args_schema: Type[BaseModel] = FileCopyInput
     description: str = "Create a copy of a file in a specified location"

langchain/tools/file_management/delete.py

@@ -22,6 +22,8 @@ class FileDeleteInput(BaseModel):
 
 
 class DeleteFileTool(BaseFileToolMixin, BaseTool):
+    """Tool that deletes a file."""
+
     name: str = "file_delete"
     args_schema: Type[BaseModel] = FileDeleteInput
     description: str = "Delete a file"

langchain/tools/file_management/file_search.py

@@ -30,6 +30,8 @@ class FileSearchInput(BaseModel):
 
 
 class FileSearchTool(BaseFileToolMixin, BaseTool):
+    """Tool that searches for files in a subdirectory that match a regex pattern."""
+
     name: str = "file_search"
     args_schema: Type[BaseModel] = FileSearchInput
     description: str = (

langchain/tools/file_management/list_dir.py

@@ -22,6 +22,8 @@ class DirectoryListingInput(BaseModel):
 
 
 class ListDirectoryTool(BaseFileToolMixin, BaseTool):
+    """Tool that lists files and directories in a specified folder."""
+
     name: str = "list_directory"
     args_schema: Type[BaseModel] = DirectoryListingInput
     description: str = "List files and directories in a specified folder"

langchain/tools/file_management/move.py

@@ -23,6 +23,8 @@ class FileMoveInput(BaseModel):
 
 
 class MoveFileTool(BaseFileToolMixin, BaseTool):
+    """Tool that moves a file."""
+
     name: str = "move_file"
     args_schema: Type[BaseModel] = FileMoveInput
     description: str = "Move or rename a file from one location to another"

langchain/tools/file_management/read.py

@@ -21,6 +21,8 @@ class ReadFileInput(BaseModel):
 
 
 class ReadFileTool(BaseFileToolMixin, BaseTool):
+    """Tool that reads a file."""
+
     name: str = "read_file"
     args_schema: Type[BaseModel] = ReadFileInput
     description: str = "Read file from disk"

langchain/tools/file_management/write.py

@@ -25,6 +25,8 @@ class WriteFileInput(BaseModel):
 
 
 class WriteFileTool(BaseFileToolMixin, BaseTool):
+    """Tool that writes a file to disk."""
+
     name: str = "write_file"
     args_schema: Type[BaseModel] = WriteFileInput
     description: str = "Write file to disk"

langchain/tools/gmail/base.py

@@ -20,8 +20,18 @@ else:
 
 
 class GmailBaseTool(BaseTool):
+    """Base class for Gmail tools."""
+
     api_resource: Resource = Field(default_factory=build_resource_service)
 
     @classmethod
     def from_api_resource(cls, api_resource: Resource) -> "GmailBaseTool":
+        """Create a tool from an api resource.
+
+        Args:
+            api_resource: The api resource to use.
+
+        Returns:
+            A tool.
+        """
         return cls(service=api_resource)

langchain/tools/gmail/create_draft.py

@@ -12,6 +12,8 @@ from langchain.tools.gmail.base import GmailBaseTool
 
 
 class CreateDraftSchema(BaseModel):
+    """Input for CreateDraftTool."""
+
     message: str = Field(
         ...,
         description="The message to include in the draft.",
@@ -35,6 +37,8 @@ class CreateDraftSchema(BaseModel):
 
 
 class GmailCreateDraft(GmailBaseTool):
+    """Tool that creates a draft email for Gmail."""
+
     name: str = "create_gmail_draft"
     description: str = (
         "Use this tool to create a draft email with the provided message fields."

langchain/tools/gmail/get_message.py

@@ -13,6 +13,8 @@ from langchain.tools.gmail.utils import clean_email_body
 
 
 class SearchArgsSchema(BaseModel):
+    """Input for GetMessageTool."""
+
     message_id: str = Field(
         ...,
         description="The unique ID of the email message, retrieved from a search.",
@@ -20,6 +22,8 @@ class SearchArgsSchema(BaseModel):
 
 
 class GmailGetMessage(GmailBaseTool):
+    """Tool that gets a message by ID from Gmail."""
+
     name: str = "get_gmail_message"
     description: str = (
         "Use this tool to fetch an email by message ID."

langchain/tools/gmail/get_thread.py

@@ -10,6 +10,8 @@ from langchain.tools.gmail.base import GmailBaseTool
 
 
 class GetThreadSchema(BaseModel):
+    """Input for GetMessageTool."""
+
     # From https://support.google.com/mail/answer/7190?hl=en
     thread_id: str = Field(
         ...,
@@ -18,6 +20,8 @@ class GetThreadSchema(BaseModel):
 
 
 class GmailGetThread(GmailBaseTool):
+    """Tool that gets a thread by ID from Gmail."""
+
     name: str = "get_gmail_thread"
     description: str = (
         "Use this tool to search for email messages."

langchain/tools/gmail/search.py

@@ -21,6 +21,8 @@ class Resource(str, Enum):
 
 
 class SearchArgsSchema(BaseModel):
+    """Input for SearchGmailTool."""
+
     # From https://support.google.com/mail/answer/7190?hl=en
     query: str = Field(
         ...,
@@ -45,6 +47,8 @@ class SearchArgsSchema(BaseModel):
 
 
 class GmailSearch(GmailBaseTool):
+    """Tool that searches for messages or threads in Gmail."""
+
     name: str = "search_gmail"
     description: str = (
         "Use this tool to search for email messages or threads."

langchain/tools/gmail/send_message.py

@@ -14,6 +14,8 @@ from langchain.tools.gmail.base import GmailBaseTool
 
 
 class SendMessageSchema(BaseModel):
+    """Input for SendMessageTool."""
+
     message: str = Field(
         ...,
         description="The message to send.",
@@ -37,6 +39,8 @@ class SendMessageSchema(BaseModel):
 
 
 class GmailSendMessage(GmailBaseTool):
+    """Tool that sends a message to Gmail."""
+
     name: str = "send_gmail_message"
     description: str = (
         "Use this tool to send email messages." " The input is the message, recipients"

langchain/tools/google_places/tool.py

@@ -13,11 +13,13 @@ from langchain.utilities.google_places_api import GooglePlacesAPIWrapper
 
 
 class GooglePlacesSchema(BaseModel):
+    """Input for GooglePlacesTool."""
+
     query: str = Field(..., description="Query for google maps")
 
 
 class GooglePlacesTool(BaseTool):
-    """Tool that adds the capability to query the Google places API."""
+    """Tool that queries the Google places API."""
 
     name = "google_places"
     description = (

langchain/tools/google_search/tool.py

@@ -11,7 +11,7 @@ from langchain.utilities.google_search import GoogleSearchAPIWrapper
 
 
 class GoogleSearchRun(BaseTool):
-    """Tool that adds the capability to query the Google search API."""
+    """Tool that queries the Google search API."""
 
     name = "google_search"
     description = (
@@ -39,7 +39,7 @@ class GoogleSearchRun(BaseTool):
 
 
 class GoogleSearchResults(BaseTool):
-    """Tool that has capability to query the Google Search API and get back json."""
+    """Tool that queries the Google Search API and gets back json."""
 
     name = "Google Search Results JSON"
     description = (

langchain/tools/google_serper/tool.py

@@ -13,7 +13,7 @@ from langchain.utilities.google_serper import GoogleSerperAPIWrapper
 
 
 class GoogleSerperRun(BaseTool):
-    """Tool that adds the capability to query the Serper.dev Google search API."""
+    """Tool that queries the Serper.dev Google search API."""
 
     name = "google_serper"
     description = (
@@ -41,7 +41,7 @@ class GoogleSerperRun(BaseTool):
 
 
 class GoogleSerperResults(BaseTool):
-    """Tool that has capability to query the Serper.dev Google Search API
+    """Tool that queries the Serper.dev Google Search API
     and get back json."""
 
     name = "google_serrper_results_json"

langchain/tools/human/tool.py

@@ -17,7 +17,7 @@ def _print_func(text: str) -> None:
 
 
 class HumanInputRun(BaseTool):
-    """Tool that adds the capability to ask user for input."""
+    """Tool that asks user for input."""
 
     name = "human"
     description = (

langchain/tools/jira/tool.py

@@ -41,6 +41,8 @@ from langchain.utilities.jira import JiraAPIWrapper
 
 
 class JiraAction(BaseTool):
+    """Tool that queries the Atlassian Jira API."""
+
     api_wrapper: JiraAPIWrapper = Field(default_factory=JiraAPIWrapper)
     mode: str
     name = ""

langchain/tools/metaphor_search/tool.py

@@ -11,7 +11,7 @@ from langchain.utilities.metaphor_search import MetaphorSearchAPIWrapper
 
 
 class MetaphorSearchResults(BaseTool):
-    """Tool that has capability to query the Metaphor Search API and get back json."""
+    """Tool that queries the Metaphor Search API and gets back json."""
 
     name = "metaphor_search_results_json"
     description = (

langchain/tools/office365/base.py

@@ -1,4 +1,4 @@
-"""Base class for Gmail tools."""
+"""Base class for Office 365 tools."""
 from __future__ import annotations
 
 from typing import TYPE_CHECKING
@@ -13,4 +13,7 @@ if TYPE_CHECKING:
 
 
 class O365BaseTool(BaseTool):
+    """Base class for the Office 365 tools."""
+
     account: Account = Field(default_factory=authenticate)
+    """The account object for the Office 365 account."""

langchain/tools/office365/create_draft_message.py

@@ -10,6 +10,8 @@ from langchain.tools.office365.base import O365BaseTool
 
 
 class CreateDraftMessageSchema(BaseModel):
+    """Input for SendMessageTool."""
+
     body: str = Field(
         ...,
         description="The message body to include in the draft.",
@@ -33,6 +35,8 @@ class CreateDraftMessageSchema(BaseModel):
 
 
 class O365CreateDraftMessage(O365BaseTool):
+    """Tool for creating a draft email in Office 365."""
+
     name: str = "create_email_draft"
     description: str = (
         "Use this tool to create a draft email with the provided message fields."

langchain/tools/office365/send_event.py

@@ -50,6 +50,8 @@ class SendEventSchema(BaseModel):
 
 
 class O365SendEvent(O365BaseTool):
+    """Tool for sending calendar events in Office 365."""
+
     name: str = "send_event"
     description: str = (
         "Use this tool to create and send an event with the provided event fields."

langchain/tools/office365/send_message.py

@@ -10,6 +10,8 @@ from langchain.tools.office365.base import O365BaseTool
 
 
 class SendMessageSchema(BaseModel):
+    """Input for SendMessageTool."""
+
     body: str = Field(
         ...,
         description="The message body to be sent.",
@@ -33,6 +35,8 @@ class SendMessageSchema(BaseModel):
 
 
 class O365SendMessage(O365BaseTool):
+    """Tool for sending an email in Office 365."""
+
     name: str = "send_email"
     description: str = (
         "Use this tool to send an email with the provided message fields."

langchain/tools/openweathermap/tool.py

@@ -13,7 +13,7 @@ from langchain.utilities import OpenWeatherMapAPIWrapper
 
 
 class OpenWeatherMapQueryRun(BaseTool):
-    """Tool that adds the capability to query using the OpenWeatherMap API."""
+    """Tool that queries the OpenWeatherMap API."""
 
     api_wrapper: OpenWeatherMapAPIWrapper = Field(
         default_factory=OpenWeatherMapAPIWrapper

langchain/tools/playwright/click.py

@@ -22,6 +22,8 @@ class ClickToolInput(BaseModel):
 
 
 class ClickTool(BaseBrowserTool):
+    """Tool for clicking on an element with the given CSS selector."""
+
     name: str = "click_element"
     description: str = "Click on an element with the given CSS selector"
     args_schema: Type[BaseModel] = ClickToolInput

langchain/tools/playwright/current_page.py

@@ -13,6 +13,8 @@ from langchain.tools.playwright.utils import aget_current_page, get_current_page
 
 
 class CurrentWebPageTool(BaseBrowserTool):
+    """Tool for getting the URL of the current webpage."""
+
     name: str = "current_webpage"
     description: str = "Returns the URL of the current page"
     args_schema: Type[BaseModel] = BaseModel

langchain/tools/playwright/extract_text.py

@@ -13,6 +13,8 @@ from langchain.tools.playwright.utils import aget_current_page, get_current_page
 
 
 class ExtractTextTool(BaseBrowserTool):
+    """Tool for extracting all the text on the current webpage."""
+
     name: str = "extract_text"
     description: str = "Extract all the text on the current webpage"
     args_schema: Type[BaseModel] = BaseModel
@@ -23,7 +25,7 @@ class ExtractTextTool(BaseBrowserTool):
         try:
             from bs4 import BeautifulSoup  # noqa: F401
         except ImportError:
-            raise ValueError(
+            raise ImportError(
                 "The 'beautifulsoup4' package is required to use this tool."
                 " Please install it with 'pip install beautifulsoup4'."
             )

langchain/tools/playwright/get_elements.py

@@ -71,6 +71,8 @@ def _get_elements(
 
 
 class GetElementsTool(BaseBrowserTool):
+    """Tool for getting elements in the current web page matching a CSS selector."""
+
     name: str = "get_elements"
     description: str = (
         "Retrieve elements in the current web page matching the given CSS selector"

langchain/tools/playwright/navigate.py

@@ -22,6 +22,8 @@ class NavigateToolInput(BaseModel):
 
 
 class NavigateTool(BaseBrowserTool):
+    """Tool for navigating a browser to a URL."""
+
     name: str = "navigate_browser"
     description: str = "Navigate a browser to the specified URL"
     args_schema: Type[BaseModel] = NavigateToolInput

langchain/tools/plugin.py

@@ -15,6 +15,8 @@ from langchain.tools.base import BaseTool
 
 
 class ApiConfig(BaseModel):
+    """API Configuration."""
+
     type: str
     url: str
     has_user_authentication: Optional[bool] = False
@@ -57,12 +59,14 @@ def marshal_spec(txt: str) -> dict:
 
 
 class AIPluginToolSchema(BaseModel):
-    """AIPLuginToolSchema."""
+    """Schema for AIPluginTool."""
 
     tool_input: Optional[str] = ""
 
 
 class AIPluginTool(BaseTool):
+    """Tool for getting the OpenAPI spec for an AI Plugin."""
+
     plugin: AIPlugin
     api_spec: str
     args_schema: Type[AIPluginToolSchema] = AIPluginToolSchema

langchain/tools/pubmed/tool.py

@@ -13,7 +13,7 @@ from langchain.utilities.pupmed import PubMedAPIWrapper
 
 
 class PubmedQueryRun(BaseTool):
-    """Tool that adds the capability to search using the PubMed API."""
+    """Tool that searches the PubMed API."""
 
     name = "PubMed"
     description = (

langchain/tools/scenexplain/tool.py

@@ -18,7 +18,7 @@ class SceneXplainInput(BaseModel):
 
 
 class SceneXplainTool(BaseTool):
-    """Tool that adds the capability to explain images."""
+    """Tool that explains images."""
 
     name = "image_explainer"
     description = (

langchain/tools/searx_search/tool.py

@@ -12,7 +12,7 @@ from langchain.utilities.searx_search import SearxSearchWrapper
 
 
 class SearxSearchRun(BaseTool):
-    """Tool that adds the capability to query a Searx instance."""
+    """Tool that queries a Searx instance."""
 
     name = "searx_search"
     description = (
@@ -41,7 +41,7 @@ class SearxSearchRun(BaseTool):
 
 
 class SearxSearchResults(BaseTool):
-    """Tool that has the capability to query a Searx instance and get back json."""
+    """Tool that queries a Searx instance and gets back json."""
 
     name = "Searx Search Results"
     description = (

langchain/tools/wikipedia/tool.py

@@ -11,7 +11,7 @@ from langchain.utilities.wikipedia import WikipediaAPIWrapper
 
 
 class WikipediaQueryRun(BaseTool):
-    """Tool that adds the capability to search using the Wikipedia API."""
+    """Tool that searches the Wikipedia API."""
 
     name = "Wikipedia"
     description = (

langchain/tools/wolfram_alpha/tool.py

@@ -11,7 +11,7 @@ from langchain.utilities.wolfram_alpha import WolframAlphaAPIWrapper
 
 
 class WolframAlphaQueryRun(BaseTool):
-    """Tool that adds the capability to query using the Wolfram Alpha SDK."""
+    """Tool that queries using the Wolfram Alpha SDK."""
 
     name = "wolfram_alpha"
     description = (

langchain/tools/youtube/search.py

@@ -19,6 +19,8 @@ from langchain.tools import BaseTool
 
 
 class YouTubeSearchTool(BaseTool):
+    """Tool that queries YouTube."""
+
     name = "youtube_search"
     description = (
         "search for youtube videos associated with a person. "