From 029e910feaac40d56f59a01b2f590494c5886992 Mon Sep 17 00:00:00 2001
From: Kevin Pham <161087761+accupham@users.noreply.github.com>
Date: Wed, 12 Feb 2025 22:03:45 -0600
Subject: [PATCH 1/9] Add method support for tool decorator
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The original tool decorator doesn't work on class methods because it unconditionally adds a self parameter treats method as if it were a plain function. That does not play nicely with Python’s bound-method behavior. This inspects the signature to prevent double-binding of self.
---
 src/smolagents/tools.py | 20 ++++++++++++++++----
 1 file changed, 16 insertions(+), 4 deletions(-)

diff --git a/src/smolagents/tools.py b/src/smolagents/tools.py
index d73fcceae..bd75893bc 100644
--- a/src/smolagents/tools.py
+++ b/src/smolagents/tools.py
@@ -873,11 +873,23 @@ def __init__(
         function=tool_function,
     )
     original_signature = inspect.signature(tool_function)
-    new_parameters = [inspect.Parameter("self", inspect.Parameter.POSITIONAL_ONLY)] + list(
-        original_signature.parameters.values()
-    )
-    new_signature = original_signature.replace(parameters=new_parameters)
+    original_params = list(original_signature.parameters.values())
+
+    # check if the function already has a "self" or "cls" as the first parameter
+    if not original_params:
+        new_params = [inspect.Parameter("self", inspect.Parameter.POSITIONAL_ONLY)]
+    else:
+        first_param_name = original_params[0].name
+        if first_param_name in ("self", "cls"):
+            # already a method signature; don't add an extra self.
+            new_params = original_params
+        else:
+            # free function signature; prepend self.
+            new_params = [inspect.Parameter("self", inspect.Parameter.POSITIONAL_ONLY)] + original_params
+
+    new_signature = original_signature.replace(parameters=new_params)
     simple_tool.forward.__signature__ = new_signature
+
     return simple_tool
 
 

From 164ba1dcb50e8a0d61f689aeb0a2f5d1c707eb6d Mon Sep 17 00:00:00 2001
From: Kevin Pham <161087761+accupham@users.noreply.github.com>
Date: Wed, 12 Feb 2025 22:39:58 -0600
Subject: [PATCH 2/9] Update tools.py

---
 src/smolagents/tools.py | 37 +++++++++++++++++++++++--------------
 1 file changed, 23 insertions(+), 14 deletions(-)

diff --git a/src/smolagents/tools.py b/src/smolagents/tools.py
index bd75893bc..5c8220436 100644
--- a/src/smolagents/tools.py
+++ b/src/smolagents/tools.py
@@ -872,24 +872,33 @@ def __init__(
         output_type=tool_json_schema["return"]["type"],
         function=tool_function,
     )
-    original_signature = inspect.signature(tool_function)
-    original_params = list(original_signature.parameters.values())
+    original_sigature = inspect.signature(tool_function)
+    original_params = list(original_sig.parameters.values())
 
-    # check if the function already has a "self" or "cls" as the first parameter
-    if not original_params:
-        new_params = [inspect.Parameter("self", inspect.Parameter.POSITIONAL_ONLY)]
-    else:
-        first_param_name = original_params[0].name
-        if first_param_name in ("self", "cls"):
-            # already a method signature; don't add an extra self.
-            new_params = original_params
+    is_method = (
+        len(original_params) > 0
+        and original_params[0].name in ("self", "cls")
+    )
+
+    @functools.wraps(tool_function)
+    def forward(*args, **kwargs):
+        if is_method:
+            return tool_function(*args, **kwargs)
         else:
-            # free function signature; prepend self.
-            new_params = [inspect.Parameter("self", inspect.Parameter.POSITIONAL_ONLY)] + original_params
+            # skip the 'self' argument.
+            return tool_function(*args[1:], **kwargs)
+
+    if is_method:
+        new_sig = original_sig
+    else:
+        new_params = [
+            inspect.Parameter("self", inspect.Parameter.POSITIONAL_ONLY)
+        ] + original_params
+        new_sig = original_signature.replace(parameters=new_params)
 
-    new_signature = original_signature.replace(parameters=new_params)
-    simple_tool.forward.__signature__ = new_signature
+    forward.__signature__ = new_sig
 
+    simple_tool.forward = forward
     return simple_tool
 
 

From 163249e83a5cc0dacbab44bcaab9677324514aa3 Mon Sep 17 00:00:00 2001
From: Kevin Pham <161087761+accupham@users.noreply.github.com>
Date: Thu, 13 Feb 2025 22:41:37 -0600
Subject: [PATCH 3/9] Update src/smolagents/tools.py

Co-authored-by: Alex <sysradium@users.noreply.github.com>
---
 src/smolagents/tools.py | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/src/smolagents/tools.py b/src/smolagents/tools.py
index 5c8220436..886df93ca 100644
--- a/src/smolagents/tools.py
+++ b/src/smolagents/tools.py
@@ -875,10 +875,7 @@ def __init__(
     original_sigature = inspect.signature(tool_function)
     original_params = list(original_sig.parameters.values())
 
-    is_method = (
-        len(original_params) > 0
-        and original_params[0].name in ("self", "cls")
-    )
+    is_method = inspect.ismethod(tool_function)
 
     @functools.wraps(tool_function)
     def forward(*args, **kwargs):

From 3c1c9937d60938d2dae854fa4e16a47629b7c79a Mon Sep 17 00:00:00 2001
From: Kevin Pham <kevin.pham@accucodeai.com>
Date: Mon, 17 Feb 2025 22:02:36 -0600
Subject: [PATCH 4/9] Add tests & documentation for tool decorators on class
 methods

---
 docs/source/en/guided_tour.md                |  49 +++++-
 src/smolagents/_function_type_hints_utils.py |  17 +-
 src/smolagents/tools.py                      |  83 +++++++---
 tests/test_tools.py                          | 161 +++++++++++++++++++
 4 files changed, 278 insertions(+), 32 deletions(-)

diff --git a/docs/source/en/guided_tour.md b/docs/source/en/guided_tour.md
index 5eca7fc21..d02cfa1ad 100644
--- a/docs/source/en/guided_tour.md
+++ b/docs/source/en/guided_tour.md
@@ -1,4 +1,4 @@
-<!--Copyright 2024 The HuggingFace Team. All rights reserved.
+from calendar import different_locale<!--Copyright 2024 The HuggingFace Team. All rights reserved.
 
 Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
 the License. You may obtain a copy of the License at
@@ -349,6 +349,53 @@ Out[20]: 'ByteDance/AnimateDiff-Lightning'
 > [!TIP]
 > Read more on tools in the [dedicated tutorial](./tutorials/tools#what-is-a-tool-and-how-to-build-one).
 
+
+### Tools from methods
+If your tool requires some form of persistent state or initialization, such as handling authentication tokens, API clients, or other shared resources, you can define it within a class.
+
+You can still use the @tool decorator, but now as a method inside a class. Let's modify our previous example to handle authentication using a Hugging Face token:
+```python
+from smolagents import tool
+
+class DownloadTools:
+    def __init__(self, hf_token: str):
+        """
+        Initializes the tool with an authentication token.
+
+        Args:
+            hf_token: Your Hugging Face API token.
+        """
+        self.hf_token = hf_token
+      
+    @tool
+    def model_download_tool(self, task: str) -> str:
+        """
+        Returns the most downloaded model of a given task on the Hugging Face Hub.
+        Uses the authentication token from initialization.
+
+        Args:
+            task: The task for which to get the most downloaded model.
+        """
+        most_downloaded_model = next(iter(
+            list_models(
+                filter=task,
+                sort="downloads",
+                direction=-1,
+                token=self.hf_token  # Pass the token from init
+            )
+        ))
+        return most_downloaded_model.id
+
+# Usage:
+dl_tools = DownloadTools(hf_token="hf_xxxxxxxx")
+agent = CodeAgent(tools=[dl_tools.model_download_tool], model=HfApiModel())
+```
+
+> [!TIP]
+> You can define multiple tools in a single class by decorating multiple methods with @tool.
+> Additionally, you can combine both function-based and class-based tools within the same agent—choose the approach that best fits your needs!
+ 
+
 ## Multi-agents
 
 Multi-agent systems have been introduced with Microsoft's framework [Autogen](https://huggingface.co/papers/2308.08155).
diff --git a/src/smolagents/_function_type_hints_utils.py b/src/smolagents/_function_type_hints_utils.py
index 13c6a2548..a528ce6d0 100644
--- a/src/smolagents/_function_type_hints_utils.py
+++ b/src/smolagents/_function_type_hints_utils.py
@@ -83,7 +83,11 @@ class DocstringParsingException(Exception):
     """Exception raised for errors in parsing docstrings to generate JSON schemas"""
 
 
-def get_json_schema(func: Callable) -> Dict:
+class ToolCreationException(Exception):
+    """Exception raised for errors in creating a tool from a function or method"""
+
+
+def get_json_schema(func: Callable, skip_self_cls: bool = False) -> Dict:
     """
     This function generates a JSON schema for a given function, based on its docstring and type hints. This is
     mostly used for passing lists of tools to a chat template. The JSON schema contains the name and description of
@@ -96,6 +100,7 @@ def get_json_schema(func: Callable) -> Dict:
 
     Args:
         func: The function to generate a JSON schema for.
+        skip_self_cls: Whether to skip the `self` and `cls` arguments in the schema. This is useful for bound methods in classes.
 
     Returns:
         A dictionary containing the JSON schema for the function.
@@ -197,8 +202,7 @@ def get_json_schema(func: Callable) -> Dict:
         )
     doc = doc.strip()
     main_doc, param_descriptions, return_doc = _parse_google_format_docstring(doc)
-
-    json_schema = _convert_type_hints_to_json_schema(func)
+    json_schema = _convert_type_hints_to_json_schema(func, skip_self_cls=skip_self_cls)
     if (return_dict := json_schema["properties"].pop("return", None)) is not None:
         if return_doc is not None:  # We allow a missing return docstring since most templates ignore it
             return_dict["description"] = return_doc
@@ -273,16 +277,19 @@ def _parse_google_format_docstring(
     return description, args_dict, returns
 
 
-def _convert_type_hints_to_json_schema(func: Callable, error_on_missing_type_hints: bool = True) -> Dict:
+def _convert_type_hints_to_json_schema(
+    func: Callable, error_on_missing_type_hints: bool = True, skip_self_cls: bool = False
+) -> Dict:
     type_hints = get_type_hints(func)
     signature = inspect.signature(func)
-
     properties = {}
     for param_name, param_type in type_hints.items():
         properties[param_name] = _parse_type_hint(param_type)
 
     required = []
     for param_name, param in signature.parameters.items():
+        if skip_self_cls and param_name in ["self", "cls"]:
+            continue
         if param.annotation == inspect.Parameter.empty and error_on_missing_type_hints:
             raise TypeHintParsingException(f"Argument {param.name} is missing a type hint in function {func.__name__}")
         if param_name not in properties:
diff --git a/src/smolagents/tools.py b/src/smolagents/tools.py
index ee7621cf2..9ba09c6a2 100644
--- a/src/smolagents/tools.py
+++ b/src/smolagents/tools.py
@@ -24,7 +24,7 @@
 import textwrap
 import types
 from contextlib import contextmanager
-from functools import wraps
+from functools import wraps, partial
 from pathlib import Path
 from typing import Callable, Dict, List, Optional, Union
 
@@ -42,6 +42,7 @@
     _convert_type_hints_to_json_schema,
     get_imports,
     get_json_schema,
+    ToolCreationException,
 )
 from .agent_types import handle_agent_input_types, handle_agent_output_types
 from .tool_validation import MethodChecker, validate_tool_attributes
@@ -250,9 +251,11 @@ def replacement(match):
                 "SpaceToolWrapper",
                 "LangChainToolWrapper",
                 "GradioToolWrapper",
+                "MethodToolWrapper",
             ]:
                 raise ValueError(
-                    "Cannot save objects created with from_space, from_langchain or from_gradio, as this would create errors."
+                    "Cannot save objects created with from_space, from_langchain, from_gradio, "
+                    "or class methods decorated with @tool as this would create errors."
                 )
 
             validate_tool_attributes(self.__class__)
@@ -838,9 +841,28 @@ def tool(tool_function: Callable) -> Tool:
     Converts a function into an instance of a Tool subclass.
 
     Args:
-        tool_function: Your function. Should have type hints for each input and a type hint for the output.
+        tool_function: Your function or class method. Should have type hints for each input and a type hint for the output.
         Should also have a docstring description including an 'Args:' part where each argument is described.
     """
+    original_signature = inspect.signature(tool_function)
+    params = list(original_signature.parameters.values())
+
+    is_method = (  # inspect.ismethod won't work here because the decorator is applied before the method is bound
+        params
+        and params[0].name in ("self", "cls")
+        and hasattr(tool_function, "__qualname__")
+        and "." in tool_function.__qualname__
+    )
+
+    if is_method:
+        return _tool_from_method(tool_function, original_signature)
+    elif inspect.isfunction(tool_function):
+        return _tool_from_function(tool_function, original_signature)
+    else:
+        raise ToolCreationException("Tool decorator can only be used on functions or methods.")
+
+
+def _tool_from_function(tool_function: Callable, original_signature: inspect.Signature) -> Tool:
     tool_json_schema = get_json_schema(tool_function)["function"]
     if "return" not in tool_json_schema:
         raise TypeHintParsingException("Tool return type not found: make sure your function has a return type hint!")
@@ -868,31 +890,40 @@ def __init__(
         output_type=tool_json_schema["return"]["type"],
         function=tool_function,
     )
-    original_sigature = inspect.signature(tool_function)
-    original_params = list(original_sig.parameters.values())
-
-    is_method = inspect.ismethod(tool_function)
-
-    @functools.wraps(tool_function)
-    def forward(*args, **kwargs):
-        if is_method:
-            return tool_function(*args, **kwargs)
-        else:
-            # skip the 'self' argument.
-            return tool_function(*args[1:], **kwargs)
-
-    if is_method:
-        new_sig = original_sig
-    else:
-        new_params = [
-            inspect.Parameter("self", inspect.Parameter.POSITIONAL_ONLY)
-        ] + original_params
-        new_sig = original_signature.replace(parameters=new_params)
+    new_parameters = [inspect.Parameter("self", inspect.Parameter.POSITIONAL_ONLY)] + list(
+        original_signature.parameters.values()
+    )
+    new_signature = original_signature.replace(parameters=new_parameters)
+    simple_tool.forward.__signature__ = new_signature
+    return simple_tool
 
-    forward.__signature__ = new_sig
 
-    simple_tool.forward = forward
-    return simple_tool
+def _tool_from_method(tool_function: Callable, original_signature: inspect.Signature) -> Tool:
+    tool_json_schema = get_json_schema(tool_function, skip_self_cls=True)["function"]
+    if "return" not in tool_json_schema:
+        raise TypeHintParsingException("Tool return type not found: make sure your method has a return type hint!")
+
+    class MethodToolWrapper(Tool):
+        def __init__(self):
+            self.name = tool_json_schema["name"]
+            self.description = tool_json_schema["description"]
+            self.inputs = tool_json_schema["parameters"]["properties"]
+            self.output_type = tool_json_schema["return"]["type"]
+            self.is_initialized = True
+            # Temp forward function; will be replaced with a bound instance in __get__. (this is for sig validation)
+            self.forward = lambda: 0
+            new_parameters = [v for v in original_signature.parameters.values() if v.name not in ["self", "cls"]]
+            modified_sig = original_signature.replace(parameters=new_parameters)
+            self.forward.__signature__ = modified_sig
+
+        # When the decorator is first used, it's on an unbound class method.
+        # So we have to use a descriptor here to bind the instance to the forward method when accessed.
+        def __get__(self, instance, owner):
+            func = getattr(tool_function, "__func__", tool_function)
+            self.forward = lambda *args, **kwargs: func(instance, *args, **kwargs)
+            return self
+
+    return MethodToolWrapper()
 
 
 class PipelineTool(Tool):
diff --git a/tests/test_tools.py b/tests/test_tools.py
index cb8a8eeaa..90c26e02d 100644
--- a/tests/test_tools.py
+++ b/tests/test_tools.py
@@ -133,6 +133,58 @@ def forward(self, task: str) -> str:
         tool = HFModelDownloadsTool()
         assert list(tool.inputs.keys())[0] == "task"
 
+    def test_method_tool_init_decorator(self):
+        class ClassWithToolMethod:
+            d = 3
+
+            def __init__(self, c: int):
+                self.c = c
+
+            @tool
+            def sumfunc_instance_method(self, a: int, b: int) -> int:
+                """Sum function as instance method
+
+                Args:
+                    a: The first argument
+                    b: The second one
+                """
+                return a + b + self.c
+
+            @classmethod
+            @tool
+            def sumfunc_class_method(cls, a: int, b: int) -> int:
+                """Sum function as class method
+
+                Args:
+                    a: The first argument
+                    b: The second one
+                """
+                return a + b + cls.d
+
+            @staticmethod
+            @tool
+            def sumfunc_static_method(a: int, b: int) -> int:
+                """Sum function as static method
+
+                Args:
+                    a: The first argument
+                    b: The second one
+                """
+                return a + b + 3
+
+        initialized_tool = ClassWithToolMethod(c=3)
+        for method_type in ("instance", "class", "static"):
+            cmethod = getattr(initialized_tool, f"sumfunc_{method_type}_method")
+            assert cmethod.output_type == "integer"
+            assert cmethod.description == f"Sum function as {method_type} method"
+            assert cmethod.name == f"sumfunc_{method_type}_method"
+            assert cmethod.inputs["a"]["description"] == "The first argument"
+            assert cmethod.inputs["b"]["description"] == "The second one"
+            correct_answer = initialized_tool.sumfunc_class_method(a=7, b=19)
+            assert correct_answer == 29
+            assert cmethod.forward(a=7, b=19) == correct_answer
+            assert cmethod.forward(7, 19) == correct_answer
+
     def test_tool_init_decorator_raises_issues(self):
         with pytest.raises(Exception) as e:
 
@@ -163,6 +215,38 @@ def coolfunc(a: str, b: int) -> int:
             assert coolfunc.output_type == "number"
         assert "docstring has no description for the argument" in str(e)
 
+    def test_method_tool_init_decorator_raises_issues(self):
+        with pytest.raises(Exception) as e:
+
+            class ToolMethod:
+                @tool
+                def cool_method(self, a: str, b: int):
+                    """Cool method
+
+                    Args:
+                        a: The first argument
+                        b: The second one
+                    """
+                    return a + b
+
+            assert ToolMethod().cool_method.output_type == "number"
+        assert "Tool return type not found" in str(e)
+
+        with pytest.raises(Exception) as e:
+
+            class ToolMethod:
+                @tool
+                def cool_method(self, a: str, b: int):
+                    """Cool function
+
+                    Args:
+                        a: The first argument
+                    """
+                    return a + b
+
+            assert ToolMethod().cool_method.output_type == "number"
+        assert "docstring has no description for the argument" in str(e)
+
     def test_saving_tool_raises_error_imports_outside_function(self):
         with pytest.raises(Exception) as e:
             import numpy as np
@@ -331,6 +415,33 @@ def get_weather(location: str, celsius: Optional[bool] = False) -> str:
         assert get_weather.inputs["celsius"]["nullable"]
         assert "nullable" not in get_weather.inputs["location"]
 
+    def test_method_tool_from_decorator_optional_args(self):
+        class ToolMethod:
+            def __init__(self, desc: str):
+                self.desc = desc
+
+            @tool
+            def get_weather(self, location: str, celsius: Optional[bool] = False) -> str:
+                """
+                Get weather in the next days at given location but only if it's Paris.
+
+                Args:
+                    location: the location
+                    celsius: the temperature type
+                """
+                if location != "Paris":
+                    raise Exception("no")
+                return f"The weather in {location} is {self.desc} with sunny skies and temperatures above 30°C"
+
+        mytool = ToolMethod(desc="lovely")
+        assert "nullable" in mytool.get_weather.inputs["celsius"]
+        assert mytool.get_weather.inputs["celsius"]["nullable"]
+        assert "nullable" not in mytool.get_weather.inputs["location"]
+        assert (
+            mytool.get_weather("Paris")
+            == "The weather in Paris is lovely with sunny skies and temperatures above 30°C"
+        )
+
     def test_tool_mismatching_nullable_args_raises_error(self):
         with pytest.raises(Exception) as e:
 
@@ -407,6 +518,21 @@ def get_weather(location: str, celsius: bool = False) -> str:
 
         assert get_weather.inputs["celsius"]["nullable"]
 
+    def test_method_tool_default_parameters_is_nullable(self):
+        class ToolMethod:
+            @tool
+            def get_weather(self, location: str, celsius: bool = False) -> str:
+                """
+                Get weather in the next days at given location.
+
+                Args:
+                    location: The location to get the weather for.
+                    celsius: is the temperature given in celsius?
+                """
+                return "The weather is UNGODLY with torrential rains and temperatures below -10°C"
+
+        assert ToolMethod().get_weather.inputs["celsius"]["nullable"]
+
     def test_tool_supports_any_none(self):
         @tool
         def get_weather(location: Any) -> None:
@@ -423,6 +549,24 @@ def get_weather(location: Any) -> None:
         assert get_weather.inputs["location"]["type"] == "any"
         assert get_weather.output_type == "null"
 
+    def test_method_tool_errors_on_save(self):
+        class ToolMethod:
+            @tool
+            def get_weather(self, location: Any) -> None:
+                """
+                Get weather in the next days at given location.
+
+                Args:
+                    location: The location to get the weather for.
+                """
+                return
+
+        mytool = ToolMethod()
+        with pytest.raises(Exception) as e:
+            with tempfile.TemporaryDirectory() as tmp_dir:
+                mytool.get_weather.save(tmp_dir)
+        assert "Cannot save objects created with" in str(e)
+
     def test_tool_supports_array(self):
         @tool
         def get_weather(locations: List[str], months: Optional[Tuple[str, str]] = None) -> Dict[str, float]:
@@ -438,6 +582,23 @@ def get_weather(locations: List[str], months: Optional[Tuple[str, str]] = None)
         assert get_weather.inputs["locations"]["type"] == "array"
         assert get_weather.inputs["months"]["type"] == "array"
 
+    def test_method_tool_supports_array(self):
+        class ToolMethod:
+            @tool
+            def get_weather(self, locations: List[str], months: Optional[Tuple[str, str]] = None) -> Dict[str, float]:
+                """
+                Get weather in the next days at given locations.
+
+                Args:
+                    locations: The locations to get the weather for.
+                    months: The months to get the weather for
+                """
+                return
+
+        mytool = ToolMethod()
+        assert mytool.get_weather.inputs["locations"]["type"] == "array"
+        assert mytool.get_weather.inputs["months"]["type"] == "array"
+
     def test_saving_tool_produces_valid_pyhon_code_with_multiline_description(self):
         @tool
         def get_weather(location: Any) -> None:

From b9fb88e030b5f3e183f299bccaa007218552e79c Mon Sep 17 00:00:00 2001
From: Kevin Pham <kevin.pham@accucodeai.com>
Date: Mon, 17 Feb 2025 22:02:36 -0600
Subject: [PATCH 5/9] Add tests & documentation for tool decorators on class
 methods

---
 docs/source/en/guided_tour.md                |  47 ++++++
 src/smolagents/_function_type_hints_utils.py |  17 +-
 src/smolagents/tools.py                      |  83 +++++++---
 tests/test_tools.py                          | 161 +++++++++++++++++++
 4 files changed, 277 insertions(+), 31 deletions(-)

diff --git a/docs/source/en/guided_tour.md b/docs/source/en/guided_tour.md
index 5eca7fc21..36f03fa32 100644
--- a/docs/source/en/guided_tour.md
+++ b/docs/source/en/guided_tour.md
@@ -349,6 +349,53 @@ Out[20]: 'ByteDance/AnimateDiff-Lightning'
 > [!TIP]
 > Read more on tools in the [dedicated tutorial](./tutorials/tools#what-is-a-tool-and-how-to-build-one).
 
+
+### Tools from methods
+If your tool requires some form of persistent state or initialization, such as handling authentication tokens, API clients, or other shared resources, you can define it within a class.
+
+You can still use the @tool decorator, but now as a method inside a class. Let's modify our previous example to handle authentication using a Hugging Face token:
+```python
+from smolagents import tool
+
+class DownloadTools:
+    def __init__(self, hf_token: str):
+        """
+        Initializes the tool with an authentication token.
+
+        Args:
+            hf_token: Your Hugging Face API token.
+        """
+        self.hf_token = hf_token
+      
+    @tool
+    def model_download_tool(self, task: str) -> str:
+        """
+        Returns the most downloaded model of a given task on the Hugging Face Hub.
+        Uses the authentication token from initialization.
+
+        Args:
+            task: The task for which to get the most downloaded model.
+        """
+        most_downloaded_model = next(iter(
+            list_models(
+                filter=task,
+                sort="downloads",
+                direction=-1,
+                token=self.hf_token  # Pass the token from init
+            )
+        ))
+        return most_downloaded_model.id
+
+# Usage:
+dl_tools = DownloadTools(hf_token="hf_xxxxxxxx")
+agent = CodeAgent(tools=[dl_tools.model_download_tool], model=HfApiModel())
+```
+
+> [!TIP]
+> You can define multiple tools in a single class by decorating multiple methods with @tool.
+> Additionally, you can combine both function-based and class-based tools within the same agent—choose the approach that best fits your needs!
+ 
+
 ## Multi-agents
 
 Multi-agent systems have been introduced with Microsoft's framework [Autogen](https://huggingface.co/papers/2308.08155).
diff --git a/src/smolagents/_function_type_hints_utils.py b/src/smolagents/_function_type_hints_utils.py
index 13c6a2548..a528ce6d0 100644
--- a/src/smolagents/_function_type_hints_utils.py
+++ b/src/smolagents/_function_type_hints_utils.py
@@ -83,7 +83,11 @@ class DocstringParsingException(Exception):
     """Exception raised for errors in parsing docstrings to generate JSON schemas"""
 
 
-def get_json_schema(func: Callable) -> Dict:
+class ToolCreationException(Exception):
+    """Exception raised for errors in creating a tool from a function or method"""
+
+
+def get_json_schema(func: Callable, skip_self_cls: bool = False) -> Dict:
     """
     This function generates a JSON schema for a given function, based on its docstring and type hints. This is
     mostly used for passing lists of tools to a chat template. The JSON schema contains the name and description of
@@ -96,6 +100,7 @@ def get_json_schema(func: Callable) -> Dict:
 
     Args:
         func: The function to generate a JSON schema for.
+        skip_self_cls: Whether to skip the `self` and `cls` arguments in the schema. This is useful for bound methods in classes.
 
     Returns:
         A dictionary containing the JSON schema for the function.
@@ -197,8 +202,7 @@ def get_json_schema(func: Callable) -> Dict:
         )
     doc = doc.strip()
     main_doc, param_descriptions, return_doc = _parse_google_format_docstring(doc)
-
-    json_schema = _convert_type_hints_to_json_schema(func)
+    json_schema = _convert_type_hints_to_json_schema(func, skip_self_cls=skip_self_cls)
     if (return_dict := json_schema["properties"].pop("return", None)) is not None:
         if return_doc is not None:  # We allow a missing return docstring since most templates ignore it
             return_dict["description"] = return_doc
@@ -273,16 +277,19 @@ def _parse_google_format_docstring(
     return description, args_dict, returns
 
 
-def _convert_type_hints_to_json_schema(func: Callable, error_on_missing_type_hints: bool = True) -> Dict:
+def _convert_type_hints_to_json_schema(
+    func: Callable, error_on_missing_type_hints: bool = True, skip_self_cls: bool = False
+) -> Dict:
     type_hints = get_type_hints(func)
     signature = inspect.signature(func)
-
     properties = {}
     for param_name, param_type in type_hints.items():
         properties[param_name] = _parse_type_hint(param_type)
 
     required = []
     for param_name, param in signature.parameters.items():
+        if skip_self_cls and param_name in ["self", "cls"]:
+            continue
         if param.annotation == inspect.Parameter.empty and error_on_missing_type_hints:
             raise TypeHintParsingException(f"Argument {param.name} is missing a type hint in function {func.__name__}")
         if param_name not in properties:
diff --git a/src/smolagents/tools.py b/src/smolagents/tools.py
index ee7621cf2..9ba09c6a2 100644
--- a/src/smolagents/tools.py
+++ b/src/smolagents/tools.py
@@ -24,7 +24,7 @@
 import textwrap
 import types
 from contextlib import contextmanager
-from functools import wraps
+from functools import wraps, partial
 from pathlib import Path
 from typing import Callable, Dict, List, Optional, Union
 
@@ -42,6 +42,7 @@
     _convert_type_hints_to_json_schema,
     get_imports,
     get_json_schema,
+    ToolCreationException,
 )
 from .agent_types import handle_agent_input_types, handle_agent_output_types
 from .tool_validation import MethodChecker, validate_tool_attributes
@@ -250,9 +251,11 @@ def replacement(match):
                 "SpaceToolWrapper",
                 "LangChainToolWrapper",
                 "GradioToolWrapper",
+                "MethodToolWrapper",
             ]:
                 raise ValueError(
-                    "Cannot save objects created with from_space, from_langchain or from_gradio, as this would create errors."
+                    "Cannot save objects created with from_space, from_langchain, from_gradio, "
+                    "or class methods decorated with @tool as this would create errors."
                 )
 
             validate_tool_attributes(self.__class__)
@@ -838,9 +841,28 @@ def tool(tool_function: Callable) -> Tool:
     Converts a function into an instance of a Tool subclass.
 
     Args:
-        tool_function: Your function. Should have type hints for each input and a type hint for the output.
+        tool_function: Your function or class method. Should have type hints for each input and a type hint for the output.
         Should also have a docstring description including an 'Args:' part where each argument is described.
     """
+    original_signature = inspect.signature(tool_function)
+    params = list(original_signature.parameters.values())
+
+    is_method = (  # inspect.ismethod won't work here because the decorator is applied before the method is bound
+        params
+        and params[0].name in ("self", "cls")
+        and hasattr(tool_function, "__qualname__")
+        and "." in tool_function.__qualname__
+    )
+
+    if is_method:
+        return _tool_from_method(tool_function, original_signature)
+    elif inspect.isfunction(tool_function):
+        return _tool_from_function(tool_function, original_signature)
+    else:
+        raise ToolCreationException("Tool decorator can only be used on functions or methods.")
+
+
+def _tool_from_function(tool_function: Callable, original_signature: inspect.Signature) -> Tool:
     tool_json_schema = get_json_schema(tool_function)["function"]
     if "return" not in tool_json_schema:
         raise TypeHintParsingException("Tool return type not found: make sure your function has a return type hint!")
@@ -868,31 +890,40 @@ def __init__(
         output_type=tool_json_schema["return"]["type"],
         function=tool_function,
     )
-    original_sigature = inspect.signature(tool_function)
-    original_params = list(original_sig.parameters.values())
-
-    is_method = inspect.ismethod(tool_function)
-
-    @functools.wraps(tool_function)
-    def forward(*args, **kwargs):
-        if is_method:
-            return tool_function(*args, **kwargs)
-        else:
-            # skip the 'self' argument.
-            return tool_function(*args[1:], **kwargs)
-
-    if is_method:
-        new_sig = original_sig
-    else:
-        new_params = [
-            inspect.Parameter("self", inspect.Parameter.POSITIONAL_ONLY)
-        ] + original_params
-        new_sig = original_signature.replace(parameters=new_params)
+    new_parameters = [inspect.Parameter("self", inspect.Parameter.POSITIONAL_ONLY)] + list(
+        original_signature.parameters.values()
+    )
+    new_signature = original_signature.replace(parameters=new_parameters)
+    simple_tool.forward.__signature__ = new_signature
+    return simple_tool
 
-    forward.__signature__ = new_sig
 
-    simple_tool.forward = forward
-    return simple_tool
+def _tool_from_method(tool_function: Callable, original_signature: inspect.Signature) -> Tool:
+    tool_json_schema = get_json_schema(tool_function, skip_self_cls=True)["function"]
+    if "return" not in tool_json_schema:
+        raise TypeHintParsingException("Tool return type not found: make sure your method has a return type hint!")
+
+    class MethodToolWrapper(Tool):
+        def __init__(self):
+            self.name = tool_json_schema["name"]
+            self.description = tool_json_schema["description"]
+            self.inputs = tool_json_schema["parameters"]["properties"]
+            self.output_type = tool_json_schema["return"]["type"]
+            self.is_initialized = True
+            # Temp forward function; will be replaced with a bound instance in __get__. (this is for sig validation)
+            self.forward = lambda: 0
+            new_parameters = [v for v in original_signature.parameters.values() if v.name not in ["self", "cls"]]
+            modified_sig = original_signature.replace(parameters=new_parameters)
+            self.forward.__signature__ = modified_sig
+
+        # When the decorator is first used, it's on an unbound class method.
+        # So we have to use a descriptor here to bind the instance to the forward method when accessed.
+        def __get__(self, instance, owner):
+            func = getattr(tool_function, "__func__", tool_function)
+            self.forward = lambda *args, **kwargs: func(instance, *args, **kwargs)
+            return self
+
+    return MethodToolWrapper()
 
 
 class PipelineTool(Tool):
diff --git a/tests/test_tools.py b/tests/test_tools.py
index cb8a8eeaa..90c26e02d 100644
--- a/tests/test_tools.py
+++ b/tests/test_tools.py
@@ -133,6 +133,58 @@ def forward(self, task: str) -> str:
         tool = HFModelDownloadsTool()
         assert list(tool.inputs.keys())[0] == "task"
 
+    def test_method_tool_init_decorator(self):
+        class ClassWithToolMethod:
+            d = 3
+
+            def __init__(self, c: int):
+                self.c = c
+
+            @tool
+            def sumfunc_instance_method(self, a: int, b: int) -> int:
+                """Sum function as instance method
+
+                Args:
+                    a: The first argument
+                    b: The second one
+                """
+                return a + b + self.c
+
+            @classmethod
+            @tool
+            def sumfunc_class_method(cls, a: int, b: int) -> int:
+                """Sum function as class method
+
+                Args:
+                    a: The first argument
+                    b: The second one
+                """
+                return a + b + cls.d
+
+            @staticmethod
+            @tool
+            def sumfunc_static_method(a: int, b: int) -> int:
+                """Sum function as static method
+
+                Args:
+                    a: The first argument
+                    b: The second one
+                """
+                return a + b + 3
+
+        initialized_tool = ClassWithToolMethod(c=3)
+        for method_type in ("instance", "class", "static"):
+            cmethod = getattr(initialized_tool, f"sumfunc_{method_type}_method")
+            assert cmethod.output_type == "integer"
+            assert cmethod.description == f"Sum function as {method_type} method"
+            assert cmethod.name == f"sumfunc_{method_type}_method"
+            assert cmethod.inputs["a"]["description"] == "The first argument"
+            assert cmethod.inputs["b"]["description"] == "The second one"
+            correct_answer = initialized_tool.sumfunc_class_method(a=7, b=19)
+            assert correct_answer == 29
+            assert cmethod.forward(a=7, b=19) == correct_answer
+            assert cmethod.forward(7, 19) == correct_answer
+
     def test_tool_init_decorator_raises_issues(self):
         with pytest.raises(Exception) as e:
 
@@ -163,6 +215,38 @@ def coolfunc(a: str, b: int) -> int:
             assert coolfunc.output_type == "number"
         assert "docstring has no description for the argument" in str(e)
 
+    def test_method_tool_init_decorator_raises_issues(self):
+        with pytest.raises(Exception) as e:
+
+            class ToolMethod:
+                @tool
+                def cool_method(self, a: str, b: int):
+                    """Cool method
+
+                    Args:
+                        a: The first argument
+                        b: The second one
+                    """
+                    return a + b
+
+            assert ToolMethod().cool_method.output_type == "number"
+        assert "Tool return type not found" in str(e)
+
+        with pytest.raises(Exception) as e:
+
+            class ToolMethod:
+                @tool
+                def cool_method(self, a: str, b: int):
+                    """Cool function
+
+                    Args:
+                        a: The first argument
+                    """
+                    return a + b
+
+            assert ToolMethod().cool_method.output_type == "number"
+        assert "docstring has no description for the argument" in str(e)
+
     def test_saving_tool_raises_error_imports_outside_function(self):
         with pytest.raises(Exception) as e:
             import numpy as np
@@ -331,6 +415,33 @@ def get_weather(location: str, celsius: Optional[bool] = False) -> str:
         assert get_weather.inputs["celsius"]["nullable"]
         assert "nullable" not in get_weather.inputs["location"]
 
+    def test_method_tool_from_decorator_optional_args(self):
+        class ToolMethod:
+            def __init__(self, desc: str):
+                self.desc = desc
+
+            @tool
+            def get_weather(self, location: str, celsius: Optional[bool] = False) -> str:
+                """
+                Get weather in the next days at given location but only if it's Paris.
+
+                Args:
+                    location: the location
+                    celsius: the temperature type
+                """
+                if location != "Paris":
+                    raise Exception("no")
+                return f"The weather in {location} is {self.desc} with sunny skies and temperatures above 30°C"
+
+        mytool = ToolMethod(desc="lovely")
+        assert "nullable" in mytool.get_weather.inputs["celsius"]
+        assert mytool.get_weather.inputs["celsius"]["nullable"]
+        assert "nullable" not in mytool.get_weather.inputs["location"]
+        assert (
+            mytool.get_weather("Paris")
+            == "The weather in Paris is lovely with sunny skies and temperatures above 30°C"
+        )
+
     def test_tool_mismatching_nullable_args_raises_error(self):
         with pytest.raises(Exception) as e:
 
@@ -407,6 +518,21 @@ def get_weather(location: str, celsius: bool = False) -> str:
 
         assert get_weather.inputs["celsius"]["nullable"]
 
+    def test_method_tool_default_parameters_is_nullable(self):
+        class ToolMethod:
+            @tool
+            def get_weather(self, location: str, celsius: bool = False) -> str:
+                """
+                Get weather in the next days at given location.
+
+                Args:
+                    location: The location to get the weather for.
+                    celsius: is the temperature given in celsius?
+                """
+                return "The weather is UNGODLY with torrential rains and temperatures below -10°C"
+
+        assert ToolMethod().get_weather.inputs["celsius"]["nullable"]
+
     def test_tool_supports_any_none(self):
         @tool
         def get_weather(location: Any) -> None:
@@ -423,6 +549,24 @@ def get_weather(location: Any) -> None:
         assert get_weather.inputs["location"]["type"] == "any"
         assert get_weather.output_type == "null"
 
+    def test_method_tool_errors_on_save(self):
+        class ToolMethod:
+            @tool
+            def get_weather(self, location: Any) -> None:
+                """
+                Get weather in the next days at given location.
+
+                Args:
+                    location: The location to get the weather for.
+                """
+                return
+
+        mytool = ToolMethod()
+        with pytest.raises(Exception) as e:
+            with tempfile.TemporaryDirectory() as tmp_dir:
+                mytool.get_weather.save(tmp_dir)
+        assert "Cannot save objects created with" in str(e)
+
     def test_tool_supports_array(self):
         @tool
         def get_weather(locations: List[str], months: Optional[Tuple[str, str]] = None) -> Dict[str, float]:
@@ -438,6 +582,23 @@ def get_weather(locations: List[str], months: Optional[Tuple[str, str]] = None)
         assert get_weather.inputs["locations"]["type"] == "array"
         assert get_weather.inputs["months"]["type"] == "array"
 
+    def test_method_tool_supports_array(self):
+        class ToolMethod:
+            @tool
+            def get_weather(self, locations: List[str], months: Optional[Tuple[str, str]] = None) -> Dict[str, float]:
+                """
+                Get weather in the next days at given locations.
+
+                Args:
+                    locations: The locations to get the weather for.
+                    months: The months to get the weather for
+                """
+                return
+
+        mytool = ToolMethod()
+        assert mytool.get_weather.inputs["locations"]["type"] == "array"
+        assert mytool.get_weather.inputs["months"]["type"] == "array"
+
     def test_saving_tool_produces_valid_pyhon_code_with_multiline_description(self):
         @tool
         def get_weather(location: Any) -> None:

From 2d40a5a0ab0f4a57fe07a27ad0523aa67e161d02 Mon Sep 17 00:00:00 2001
From: Kevin Pham <kevin.pham@accucodeai.com>
Date: Mon, 17 Feb 2025 22:12:09 -0600
Subject: [PATCH 6/9] lint

---
 src/smolagents/tools.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/smolagents/tools.py b/src/smolagents/tools.py
index 9ba09c6a2..dab05ffd4 100644
--- a/src/smolagents/tools.py
+++ b/src/smolagents/tools.py
@@ -24,7 +24,7 @@
 import textwrap
 import types
 from contextlib import contextmanager
-from functools import wraps, partial
+from functools import wraps
 from pathlib import Path
 from typing import Callable, Dict, List, Optional, Union
 
@@ -38,11 +38,11 @@
 from huggingface_hub.utils import is_torch_available
 
 from ._function_type_hints_utils import (
+    ToolCreationException,
     TypeHintParsingException,
     _convert_type_hints_to_json_schema,
     get_imports,
     get_json_schema,
-    ToolCreationException,
 )
 from .agent_types import handle_agent_input_types, handle_agent_output_types
 from .tool_validation import MethodChecker, validate_tool_attributes

From 9123ae64614c89af0cc2442ec891f8db6ac7b3a5 Mon Sep 17 00:00:00 2001
From: Kevin Pham <kevin.pham@accucodeai.com>
Date: Tue, 18 Feb 2025 09:30:51 -0600
Subject: [PATCH 7/9] fix typo

---
 docs/source/en/guided_tour.md     | 2 +-
 docs/source/en/tutorials/tools.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/source/en/guided_tour.md b/docs/source/en/guided_tour.md
index d02cfa1ad..36f03fa32 100644
--- a/docs/source/en/guided_tour.md
+++ b/docs/source/en/guided_tour.md
@@ -1,4 +1,4 @@
-from calendar import different_locale<!--Copyright 2024 The HuggingFace Team. All rights reserved.
+<!--Copyright 2024 The HuggingFace Team. All rights reserved.
 
 Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
 the License. You may obtain a copy of the License at
diff --git a/docs/source/en/tutorials/tools.md b/docs/source/en/tutorials/tools.md
index d9da1e94f..8e7a19d92 100644
--- a/docs/source/en/tutorials/tools.md
+++ b/docs/source/en/tutorials/tools.md
@@ -76,7 +76,7 @@ The custom tool subclasses [`Tool`] to inherit useful methods. The child class a
 
 And that's all it needs to be used in an agent!
 
-There's another way to build a tool. In the [guided_tour](../guided_tour), we implemented a tool using the `@tool` decorator. The [`tool`] decorator is the recommended way to define simple tools, but sometimes you need more than this: using several methods in a class for more clarity, or using additional class attributes.
+There's another way to build a tool. In the [guided_tour](../guided_tour), we implemented a tool using the `@tool` decorator on a function The [`tool`] decorator is the recommended way to define simple tools, but sometimes you need more than this: using several methods in a class for more clarity, or using additional class attributes.
 
 In this case, you can build your tool by subclassing [`Tool`] as described above.
 

From e74e31b46112c922e8b3c9067e7697172f345a0b Mon Sep 17 00:00:00 2001
From: Kevin Pham <kevin.pham@accucodeai.com>
Date: Tue, 18 Feb 2025 09:50:45 -0600
Subject: [PATCH 8/9] update wording on documentation

---
 docs/source/en/guided_tour.md | 14 ++++----------
 1 file changed, 4 insertions(+), 10 deletions(-)

diff --git a/docs/source/en/guided_tour.md b/docs/source/en/guided_tour.md
index 36f03fa32..d535ba11f 100644
--- a/docs/source/en/guided_tour.md
+++ b/docs/source/en/guided_tour.md
@@ -351,20 +351,14 @@ Out[20]: 'ByteDance/AnimateDiff-Lightning'
 
 
 ### Tools from methods
-If your tool requires some form of persistent state or initialization, such as handling authentication tokens, API clients, or other shared resources, you can define it within a class.
+Sometimes, you need to preserve state or perform an initialization step, such as handling tokens, setting up API clients, or sharing resources among tools. In these cases, you can encapsulate a tool within a class method.
 
-You can still use the @tool decorator, but now as a method inside a class. Let's modify our previous example to handle authentication using a Hugging Face token:
+You still use the @tool decorator, but you apply it directly to a method. Let's modify our previous example to handle authentication using a HuggingFace token:
 ```python
 from smolagents import tool
 
 class DownloadTools:
     def __init__(self, hf_token: str):
-        """
-        Initializes the tool with an authentication token.
-
-        Args:
-            hf_token: Your Hugging Face API token.
-        """
         self.hf_token = hf_token
       
     @tool
@@ -392,8 +386,8 @@ agent = CodeAgent(tools=[dl_tools.model_download_tool], model=HfApiModel())
 ```
 
 > [!TIP]
-> You can define multiple tools in a single class by decorating multiple methods with @tool.
-> Additionally, you can combine both function-based and class-based tools within the same agent—choose the approach that best fits your needs!
+> You can create multiple tools in a single class by decorating more methods with @tool.
+> You can also mix class-based and function-based tools in the same agent. Go with whichever approach suits your needs best!
  
 
 ## Multi-agents

From ccf4c206d393e8c629bee1c70d601dd3d4b3622f Mon Sep 17 00:00:00 2001
From: Kevin Pham <kevin.pham@accucodeai.com>
Date: Tue, 18 Feb 2025 10:19:38 -0600
Subject: [PATCH 9/9] fix mdx check on test

---
 tests/test_all_docs.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/test_all_docs.py b/tests/test_all_docs.py
index 7dcbf5838..6df8dc76c 100644
--- a/tests/test_all_docs.py
+++ b/tests/test_all_docs.py
@@ -94,7 +94,7 @@ def setup_class(cls):
 
         load_dotenv()
 
-        cls.md_files = list(cls.docs_dir.rglob("*.md"))
+        cls.md_files = list(cls.docs_dir.rglob("*.mdx"))
         if not cls.md_files:
             raise ValueError(f"No markdown files found in {cls.docs_dir}")