huggingface/smolagents · error · TypeHintParsingException

Tool return type not found: make sure your function has a re

Error message

Tool return type not found: make sure your function has a return type hint!

What it means

The @tool decorator builds a JSON schema for the wrapped function and requires a return annotation. If no return type hint is present and the function takes no parameters, smolagents assumes a null return; otherwise it raises TypeHintParsingException because downstream agents need the return type to interpret tool output.

Source

Thrown at src/smolagents/tools.py:1076

            yield cls(tools)


def tool(tool_function: Callable) -> Tool:
    """
    Convert a function into an instance of a dynamically created Tool subclass.

    Args:
        tool_function (`Callable`): Function to convert into a Tool subclass.
            Should have type hints for each input and a type hint for the output.
            Should also have a docstring including the description of the function
            and an 'Args:' part where each argument is described.
    """
    tool_json_schema = get_json_schema(tool_function)["function"]
    if "return" not in tool_json_schema:
        if len(tool_json_schema["parameters"]["properties"]) == 0:
            tool_json_schema["return"] = {"type": "null"}
        else:
            raise TypeHintParsingException(
                "Tool return type not found: make sure your function has a return type hint!"
            )

    class SimpleTool(Tool):
        def __init__(self):
            self.is_initialized = True

    # Set the class attributes
    SimpleTool.name = tool_json_schema["name"]
    SimpleTool.description = tool_json_schema["description"]
    SimpleTool.inputs = tool_json_schema["parameters"]["properties"]
    SimpleTool.output_type = tool_json_schema["return"]["type"]

    # Set output_schema if it exists in the JSON schema
    if "output_schema" in tool_json_schema:
        SimpleTool.output_schema = tool_json_schema["output_schema"]
    elif "return" in tool_json_schema and "schema" in tool_json_schema["return"]:
        SimpleTool.output_schema = tool_json_schema["return"]["schema"]

View on GitHub (pinned to 30bb116109)

Solutions

Add an explicit return type hint to the function (e.g. `-> str`, `-> int`, or `-> None` for void tools)
Annotate parameter types too so input schema generation is accurate
Run a quick lint (mypy --strict or pyright) on tool modules to catch missing annotations

Example fix

# before
@tool
def get_weather(city: str):
    return fetch(city)
# after
@tool
def get_weather(city: str) -> str:
    return fetch(city)

Defensive patterns

Strategy: type-guard

Validate before calling

import inspect
sig = inspect.signature(my_func)
if sig.return_annotation is inspect.Signature.empty and sig.parameters:
    raise TypeError("add a return type hint before wrapping with @tool")

Type guard

def is_tool_ready(func) -> bool:
    sig = inspect.signature(func)
    return sig.return_annotation is not inspect.Signature.empty or not sig.parameters

Try / catch

from smolagents.utils import TypeHintParsingException
try:
    my_tool = tool(my_func)
except TypeHintParsingException:
    my_func.__annotations__['return'] = str
    my_tool = tool(my_func)

Prevention

Always annotate tool functions' parameters and return types
Run mypy/pyright over tool modules
Use `-> None` explicitly for tools returning nothing

When it happens

Trigger: Applying `@tool` to a function that has one or more parameters but no `-> ...` return annotation, e.g. `def add(a: int, b: int):` (missing `-> int`). Zero-arg functions without hints fall back to a null type and do not raise.

Common situations: Quickly wrapping existing helper functions as agent tools without adding type hints; functions returning None implicitly where the author forgot `-> None`.

Related errors

AI-assisted analysis of huggingface/smolagents@30bb116109 (2026-08-28). Data as JSON: /api/errors/7ec86cf54693dd2e. Report an issue: GitHub.