[docs]: standardize tool docstrings (#25351)

docs/vercel.json

@@ -93,6 +93,14 @@
     {
       "source": "/v0.2/docs/integrations/toolkits/:path(.*/?)*",
       "destination": "/v0.2/docs/integrations/tools/:path*"
+    },
+    {
+      "source": "/v0.2/docs/integrations/toolkits/spark/",
+      "destination": "/v0.2/docs/integrations/tools/spark_sql/"
+    },
+    {
+      "source": "/v0.2/docs/integrations/toolkits/xorbits/",
+      "destination": "/v0.2/docs/integrations/tools#search"
     }
   ]
 }

libs/cli/langchain_cli/integration_template/integration_template/tools.py

@@ -57,12 +57,12 @@ class __ModuleName__Tool(BaseTool):
         .. code-block:: python
 
             # TODO: invoke args
-            tool.invoke({"args": {...}, "id": "1", "name": tool.name, "type": "tool_call})
+            tool.invoke({"args": {...}, "id": "1", "name": tool.name, "type": "tool_call"})
 
         .. code-block:: python
 
             # TODO: output of invocation
-    """
+    """ # noqa: E501
 
     # TODO: Set tool name and description
     name: str = "TODO: Tool name"

libs/community/langchain_community/tools/bing_search/tool.py

@@ -29,7 +29,45 @@ def _run(
 
 
 class BingSearchResults(BaseTool):
-    """Tool that queries the Bing Search API and gets back json."""
+    """Bing Search tool.
+
+    Setup:
+        Install ``langchain-community`` and set environment variable ``BING_SUBSCRIPTION_KEY``.
+
+        .. code-block:: bash
+
+            pip install -U langchain-community
+            export BING_SUBSCRIPTION_KEY="your-api-key"
+
+    Instantiation:
+        .. code-block:: python
+
+            from langchain_community.tools.bing_search import BingSearchResults
+            from langchain_community.utilities import BingSearchAPIWrapper
+
+            api_wrapper = BingSearchAPIWrapper()
+            tool = BingSearchResults(api_wrapper=api_wrapper)
+
+    Invocation with args:
+        .. code-block:: python
+
+            tool.invoke("what is the weather in SF?")
+
+        .. code-block:: python
+
+            "[{'snippet': '<b>San Francisco, CA</b> <b>Weather</b> Forecast, with current conditions, wind, air quality, and what to expect for the next 3 days.', 'title': 'San Francisco, CA Weather Forecast | AccuWeather', 'link': 'https://www.accuweather.com/en/us/san-francisco/94103/weather-forecast/347629'}, {'snippet': 'Tropical Storm Ernesto Forms; Fire <b>Weather</b> Concerns in the Great Basin: Hot Temperatures Return to the South-Central U.S. ... <b>San Francisco CA</b> 37.77°N 122.41°W (Elev. 131 ft) Last Update: 2:21 pm PDT Aug 12, 2024. Forecast Valid: 6pm PDT Aug 12, 2024-6pm PDT Aug 19, 2024 .', 'title': 'National Weather Service', 'link': 'https://forecast.weather.gov/zipcity.php?inputstring=San+Francisco,CA'}, {'snippet': 'Current <b>weather</b> <b>in San Francisco, CA</b>. Check current conditions <b>in San Francisco, CA</b> with radar, hourly, and more.', 'title': 'San Francisco, CA Current Weather | AccuWeather', 'link': 'https://www.accuweather.com/en/us/san-francisco/94103/current-weather/347629'}, {'snippet': 'Everything you need to know about today&#39;s <b>weather</b> <b>in San Francisco, CA</b>. High/Low, Precipitation Chances, Sunrise/Sunset, and today&#39;s Temperature History.', 'title': 'Weather Today for San Francisco, CA | AccuWeather', 'link': 'https://www.accuweather.com/en/us/san-francisco/94103/weather-today/347629'}]"
+
+    Invocation with ToolCall:
+
+        .. code-block:: python
+
+            tool.invoke({"args": {"query":"what is the weather in SF?"}, "id": "1", "name": tool.name, "type": "tool_call"})
+
+        .. code-block:: python
+
+            ToolMessage(content="[{'snippet': 'Get the latest <b>weather</b> forecast for <b>San Francisco, CA</b>, including temperature, RealFeel, and chance of precipitation. Find out how the <b>weather</b> will affect your plans and activities in the city of ...', 'title': 'San Francisco, CA Weather Forecast | AccuWeather', 'link': 'https://www.accuweather.com/en/us/san-francisco/94103/weather-forecast/347629'}, {'snippet': 'Radar. Be prepared with the most accurate 10-day forecast for <b>San Francisco, CA</b> with highs, lows, chance of precipitation from The <b>Weather</b> Channel and <b>Weather</b>.com.', 'title': '10-Day Weather Forecast for San Francisco, CA - The Weather Channel', 'link': 'https://weather.com/weather/tenday/l/San+Francisco+CA+USCA0987:1:US'}, {'snippet': 'Tropical Storm Ernesto Forms; Fire <b>Weather</b> Concerns in the Great Basin: Hot Temperatures Return to the South-Central U.S. ... <b>San Francisco CA</b> 37.77°N 122.41°W (Elev. 131 ft) Last Update: 2:21 pm PDT Aug 12, 2024. Forecast Valid: 6pm PDT Aug 12, 2024-6pm PDT Aug 19, 2024 .', 'title': 'National Weather Service', 'link': 'https://forecast.weather.gov/zipcity.php?inputstring=San+Francisco,CA'}, {'snippet': 'Current <b>weather</b> <b>in San Francisco, CA</b>. Check current conditions <b>in San Francisco, CA</b> with radar, hourly, and more.', 'title': 'San Francisco, CA Current Weather | AccuWeather', 'link': 'https://www.accuweather.com/en/us/san-francisco/94103/current-weather/347629'}]", name='bing_search_results_json', tool_call_id='1')
+
+    """  # noqa: E501
 
     name: str = "bing_search_results_json"
     description: str = (

libs/community/langchain_community/tools/ddg_search/tool.py

@@ -17,7 +17,41 @@ class DDGInput(BaseModel):
 
 
 class DuckDuckGoSearchRun(BaseTool):
-    """Tool that queries the DuckDuckGo search API."""
+    """DuckDuckGo tool.
+
+    Setup:
+        Install ``duckduckgo-search`` and ``langchain-community``.
+
+        .. code-block:: bash
+
+            pip install -U duckduckgo-search langchain-community
+
+    Instantiation:
+        .. code-block:: python
+
+            from langchain_community.tools import DuckDuckGoSearchResults
+
+            tool = DuckDuckGoSearchResults()
+
+    Invocation with args:
+        .. code-block:: python
+
+            tool.invoke("Obama")
+
+        .. code-block:: python
+
+            '[snippet: Users on X have been widely comparing the boost of support felt for Kamala Harris\' campaign to Barack Obama\'s in 2008., title: Surging Support For Kamala Harris Compared To Obama-Era Energy, link: https://www.msn.com/en-us/news/politics/surging-support-for-kamala-harris-compared-to-obama-era-energy/ar-BB1qzdC0, date: 2024-07-24T18:27:01+00:00, source: Newsweek on MSN.com], [snippet: Harris tried to emulate Obama\'s coalition in 2020 and failed. She may have a better shot at reaching young, Black, and Latino voters this time around., title: Harris May Follow Obama\'s Path to the White House After All, link: https://www.msn.com/en-us/news/politics/harris-may-follow-obama-s-path-to-the-white-house-after-all/ar-BB1qv9d4, date: 2024-07-23T22:42:00+00:00, source: Intelligencer on MSN.com], [snippet: The Republican presidential candidate said in an interview on Fox News that he "wouldn\'t be worried" about Michelle Obama running., title: Donald Trump Responds to Michelle Obama Threat, link: https://www.msn.com/en-us/news/politics/donald-trump-responds-to-michelle-obama-threat/ar-BB1qqtu5, date: 2024-07-22T18:26:00+00:00, source: Newsweek on MSN.com], [snippet: H eading into the weekend at his vacation home in Rehoboth Beach, Del., President Biden was reportedly stewing over Barack Obama\'s role in the orchestrated campaign to force him, title: Opinion | Barack Obama Strikes Again, link: https://www.msn.com/en-us/news/politics/opinion-barack-obama-strikes-again/ar-BB1qrfiy, date: 2024-07-22T21:28:00+00:00, source: The Wall Street Journal on MSN.com]'
+
+    Invocation with ToolCall:
+
+        .. code-block:: python
+
+            tool.invoke({"args": {"query":"Obama"}, "id": "1", "name": tool.name, "type": "tool_call"})
+
+        .. code-block:: python
+
+            ToolMessage(content="[snippet: Biden, Obama and the Clintons Will Speak at the Democratic Convention. The president, two of his predecessors and the party's 2016 nominee are said to be planning speeches at the party's ..., title: Biden, Obama and the Clintons Will Speak at the Democratic Convention ..., link: https://www.nytimes.com/2024/08/12/us/politics/dnc-speakers-biden-obama-clinton.html], [snippet: Barack Obama—with his wife, Michelle—being sworn in as the 44th president of the United States, January 20, 2009. Key events in the life of Barack Obama. Barack Obama (born August 4, 1961, Honolulu, Hawaii, U.S.) is the 44th president of the United States (2009-17) and the first African American to hold the office., title: Barack Obama | Biography, Parents, Education, Presidency, Books ..., link: https://www.britannica.com/biography/Barack-Obama], [snippet: Former President Barack Obama released a letter about President Biden's decision to drop out of the 2024 presidential race. Notably, Obama did not name or endorse Vice President Kamala Harris., title: Read Obama's full statement on Biden dropping out - CBS News, link: https://www.cbsnews.com/news/barack-obama-biden-dropping-out-2024-presidential-race-full-statement/], [snippet: Many of the marquee names in Democratic politics began quickly lining up behind Vice President Kamala Harris on Sunday, but one towering presence in the party held back: Barack Obama. The former ..., title: Why Obama Hasn't Endorsed Harris - The New York Times, link: https://www.nytimes.com/2024/07/21/us/politics/why-obama-hasnt-endorsed-harris.html]", name='duckduckgo_results_json', tool_call_id='1')
+    """  # noqa: E501
 
     name: str = "duckduckgo_search"
     description: str = (

libs/community/langchain_community/tools/riza/command.py

@@ -19,7 +19,43 @@ class ExecPythonInput(BaseModel):
 
 
 class ExecPython(BaseTool):
-    """A tool implementation to execute Python via Riza's Code Interpreter API."""
+    """Riza Code tool.
+
+    Setup:
+        Install ``langchain-community`` and ``rizaio`` and set environment variable ``RIZA_API_KEY``.
+
+        .. code-block:: bash
+
+            pip install -U langchain-community rizaio
+            export RIZA_API_KEY="your-api-key"
+
+    Instantiation:
+        .. code-block:: python
+
+            from langchain_community.tools.riza.command import ExecPython
+
+            tool = ExecPython()
+
+    Invocation with args:
+        .. code-block:: python
+
+            tool.invoke("x = 5; print(x)")
+
+        .. code-block:: python
+
+            '5\\n'
+
+    Invocation with ToolCall:
+
+        .. code-block:: python
+
+            tool.invoke({"args": {"code":"x = 5; print(x)"}, "id": "1", "name": tool.name, "type": "tool_call"})
+
+        .. code-block:: python
+
+            tool.invoke({"args": {"code":"x = 5; print(x)"}, "id": "1", "name": tool.name, "type": "tool_call"})
+
+    """  # noqa: E501
 
     name: str = "riza_exec_python"
     description: str = """Execute Python code to solve problems.

libs/partners/azure-dynamic-sessions/langchain_azure_dynamic_sessions/tools/sessions.py

@@ -92,18 +92,50 @@ def from_dict(data: dict) -> "RemoteFileMetadata":
 
 
 class SessionsPythonREPLTool(BaseTool):
-    """A tool for running Python code.
+    r"""Azure Dynamic Sessions tool.
 
-     Run python code in an Azure Container Apps dynamic sessions code interpreter.
+    Setup:
+        Install ``langchain-azure-dynamic-sessions`` and create a session pool, which you can do by following the instructions [here](https://learn.microsoft.com/en-us/azure/container-apps/sessions-code-interpreter?tabs=azure-cli#create-a-session-pool-with-azure-cli).
 
-    Example:
+        .. code-block:: bash
+
+            pip install -U langchain-azure-dynamic-sessions
+
+        .. code-block:: python
+
+            import getpass
+
+            POOL_MANAGEMENT_ENDPOINT = getpass.getpass("Enter the management endpoint of the session pool: ")
+
+    Instantiation:
         .. code-block:: python
 
             from langchain_azure_dynamic_sessions import SessionsPythonREPLTool
 
-            tool = SessionsPythonREPLTool(pool_management_endpoint="...")
-            result = tool.invoke("6 * 7")
-    """
+            tool = SessionsPythonREPLTool(
+                pool_management_endpoint=POOL_MANAGEMENT_ENDPOINT
+            )
+
+
+    Invocation with args:
+        .. code-block:: python
+
+            tool.invoke("6 * 7")
+
+        .. code-block:: python
+
+            '{\\n  "result": 42,\\n  "stdout": "",\\n  "stderr": ""\\n}'
+
+    Invocation with ToolCall:
+
+        .. code-block:: python
+
+            tool.invoke({"args": {"input":"6 * 7"}, "id": "1", "name": tool.name, "type": "tool_call"})
+
+        .. code-block:: python
+
+            '{\\n  "result": 42,\\n  "stdout": "",\\n  "stderr": ""\\n}'
+    """  # noqa: E501
 
     name: str = "Python_REPL"
     description: str = (

libs/partners/exa/langchain_exa/tools.py

@@ -14,7 +14,43 @@
 
 
 class ExaSearchResults(BaseTool):
-    """Tool that queries the Metaphor Search API and gets back json."""
+    """Exa Search tool.
+
+    Setup:
+        Install ``langchain-exa`` and set environment variable ``EXA_API_KEY``.
+
+        .. code-block:: bash
+
+            pip install -U langchain-exa
+            export EXA_API_KEY="your-api-key"
+
+    Instantiation:
+        .. code-block:: python
+
+            from langchain-exa import ExaSearchResults
+
+            tool = ExaSearchResults()
+
+    Invocation with args:
+        .. code-block:: python
+
+            tool.invoke({"query":"what is the weather in SF","num_results":1})
+
+        .. code-block:: python
+
+            SearchResponse(results=[Result(url='https://www.wunderground.com/weather/37.8,-122.4', id='https://www.wunderground.com/weather/37.8,-122.4', title='San Francisco, CA Weather Conditionsstar_ratehome', score=0.1843988299369812, published_date='2023-02-23T01:17:06.594Z', author=None, text='The time period when the sun is no more than 6 degrees below the horizon at either sunrise or sunset. The horizon should be clearly defined and the brightest stars should be visible under good atmospheric conditions (i.e. no moonlight, or other lights). One still should be able to carry on ordinary outdoor activities. The time period when the sun is between 6 and 12 degrees below the horizon at either sunrise or sunset. The horizon is well defined and the outline of objects might be visible without artificial light. Ordinary outdoor activities are not possible at this time without extra illumination. The time period when the sun is between 12 and 18 degrees below the horizon at either sunrise or sunset. The sun does not contribute to the illumination of the sky before this time in the morning, or after this time in the evening. In the beginning of morning astronomical twilight and at the end of astronomical twilight in the evening, sky illumination is very faint, and might be undetectable. The time of Civil Sunset minus the time of Civil Sunrise. The time of Actual Sunset minus the time of Actual Sunrise. The change in length of daylight between today and tomorrow is also listed when available.', highlights=None, highlight_scores=None, summary=None)], autoprompt_string=None)
+
+    Invocation with ToolCall:
+
+        .. code-block:: python
+
+            tool.invoke({"args": {"query":"what is the weather in SF","num_results":1}, "id": "1", "name": tool.name, "type": "tool_call"})
+
+        .. code-block:: python
+
+            ToolMessage(content='Title: San Francisco, CA Weather Conditionsstar_ratehome\nURL: https://www.wunderground.com/weather/37.8,-122.4\nID: https://www.wunderground.com/weather/37.8,-122.4\nScore: 0.1843988299369812\nPublished Date: 2023-02-23T01:17:06.594Z\nAuthor: None\nText: The time period when the sun is no more than 6 degrees below the horizon at either sunrise or sunset. The horizon should be clearly defined and the brightest stars should be visible under good atmospheric conditions (i.e. no moonlight, or other lights). One still should be able to carry on ordinary outdoor activities. The time period when the sun is between 6 and 12 degrees below the horizon at either sunrise or sunset. The horizon is well defined and the outline of objects might be visible without artificial light. Ordinary outdoor activities are not possible at this time without extra illumination. The time period when the sun is between 12 and 18 degrees below the horizon at either sunrise or sunset. The sun does not contribute to the illumination of the sky before this time in the morning, or after this time in the evening. In the beginning of morning astronomical twilight and at the end of astronomical twilight in the evening, sky illumination is very faint, and might be undetectable. The time of Civil Sunset minus the time of Civil Sunrise. The time of Actual Sunset minus the time of Actual Sunrise. The change in length of daylight between today and tomorrow is also listed when available.\nHighlights: None\nHighlight Scores: None\nSummary: None\n', name='exa_search_results_json', tool_call_id='1')
+
+    """  # noqa: E501
 
     name: str = "exa_search_results_json"
     description: str = (