[FEATURE] Support for Type Annotations with Descriptions in @tool Decorator Functions

[jawtopi]

Problem Statement

Currently, Strands tool functions require argument descriptions to be defined in DocStrings when using the @tool decorator approach. While the tool description itself can be overridden in the decorator, there's no elegant way to handle long argument descriptions without resorting to long, unclean looking DocStrings.

Proposed Solution

Implement support for Python type + description annotations for function tool arguments. Frameworks like AutoGen already support this. Here is the AutoGen annotation feature as an example.

A Strands example could look like:

GET_STOCK_PRICE_DESCRIPTION = "Gets a random stock price for demonstration purposes"
GET_STOCK_PRICE_DATE_DESC = "Date in YYYY/MM/DD"

@tool(description=GET_STOCK_PRICE_DESCRIPTION)
async def get_stock_price(ticker: str, 
    date: Annotated[str, GET_STOCK_PRICE_DATE_DESC]
) -> float:
    return random.uniform(10, 200)

Use Case

Developers working with tools that require detailed parameter descriptions would benefit from cleaner code organization. Currently for a Python DocString, there is no method to associate specific descriptions with parameters in a structured way that tools can reliably parse.

Alternatives Solutions

One way to handle detailed parameter descriptions cleanly in Strands is to use module tools with a TOOLSPEC variable, which allows defining structured parameter descriptions separately from the function implementation. This approach enables importing description constants, and placing them into the Input Schema like this:

from random_directory import (
    ARG2_DESC
    ARG1_DESC,
    EXAMPLE_DESCRIPTION,
)

TOOL_SPEC = {
    "name": "example",
    "description": EXAMPLE_DESCRIPTION,,
    "inputSchema": {
        "json": {
            "type": "object",
            "properties": {
                "arg1": {"type": "string", "description": ARG1_DESC},
                "arg2": {"type": "string", "description": ARG2_DESC},
            },
        }
    },
}


def example(tool, **kwargs):
    return {
        "toolUseId": tool["toolUseId"],
        "status": "success",
        "content": [{"text": "just an example"}],
    }

However, module tools require each tool to be defined in a separate file with a rigid format, and sharing dependencies between tools e.g. specific class instances for per-tool state is difficult. The primary challenge is that there's no built-in mechanism for dependency injection with module tools, which makes the @tool decorator method preferrable.

Additional Context

No response

[liorheber]

Would like to ask for this to be implemented as well. Tool decorator makes tools relatively agnostic to the framework but not having the description work makes it less of a viable option.

[awsarron]

Thank you for your feedback @jawtopi @liorheber.

Strands does support overriding these values for decorated tools. Some information can be found at https://strandsagents.com/latest/documentation/docs/user-guide/concepts/tools/python-tools/#overriding-tool-name-and-description.

Here's an example:

from strands import Agent, tool

@tool(name="super_tool")
def my_tool(query: str) -> str:
    return "Dummy tool response"

agent = Agent(tools=[my_tool])

print(agent.tool_names)
agent("list your tool names and show me their responses")

Here is the output from this example:

['super_tool']
I have one tool available called "super_tool". Let me show you its response by calling it:
Tool #1: super_tool
Here are my available tools and their responses:

**Tool Name:** super_tool
- **Description:** my_tool
- **Required Parameter:** query (string)
- **Response:** "Dummy tool response"

The tool appears to return a simple dummy response regardless of the input query parameter.

The relevant SDK code:

sdk-python/src/strands/tools/decorator.py

Lines 562 to 623 in 1f27488

	"""Decorator that transforms a Python function into a Strands tool.
	This decorator seamlessly enables a function to be called both as a regular Python function and as a Strands tool.
	It extracts metadata from the function's signature, docstring, and type hints to generate an OpenAPI-compatible tool
	specification.
	When decorated, a function:
	1. Still works as a normal function when called directly with arguments
	2. Processes tool use API calls when provided with a tool use dictionary
	3. Validates inputs against the function's type hints and parameter spec
	4. Formats return values according to the expected Strands tool result format
	5. Provides automatic error handling and reporting
	The decorator can be used in two ways:
	- As a simple decorator: `@tool`
	- With parameters: `@tool(name="custom_name", description="Custom description")`
	Args:
	func: The function to decorate. When used as a simple decorator, this is the function being decorated.
	When used with parameters, this will be None.
	description: Optional custom description to override the function's docstring.
	inputSchema: Optional custom JSON schema to override the automatically generated schema.
	name: Optional custom name to override the function's name.
	context: When provided, places an object in the designated parameter. If True, the param name
	defaults to 'tool_context', or if an override is needed, set context equal to a string to designate
	the param name.
	Returns:
	An AgentTool that also mimics the original function when invoked
	Example:
	```python
	@tool
	def my_tool(name: str, count: int = 1) -> str:
	# Does something useful with the provided parameters.
	#
	# Parameters:
	# name: The name to process
	# count: Number of times to process (default: 1)
	#
	# Returns:
	# A message with the result
	return f"Processed {name} {count} times"
	agent = Agent(tools=[my_tool])
	agent.my_tool(name="example", count=3)
	# Returns: {
	# "toolUseId": "123",
	# "status": "success",
	# "content": [{"text": "Processed example 3 times"}]
	# }
	```
	Example with parameters:
	```python
	@tool(name="custom_tool", description="A tool with a custom name and description", context=True)
	def my_tool(name: str, count: int = 1, tool_context: ToolContext) -> str:
	tool_id = tool_context["tool_use"]["toolUseId"]
	return f"Processed {name} {count} times with tool ID {tool_id}"
	```
	"""

The name, description, inputSchema, and context values can be overridden during definition. I'll raise a PR to update our documentation to include the inputSchema and context values.

[liorheber]

Hi,

The request is not related to the tool name or description or the argument name and type.
I'm talking about annotation of arguments that provide description of an argument.

Say my tool accepts a query and I gave it a type string, but I also want to describe it as "the original query of the user".

So while in json schema the description will pass, with tool decorator and annotation it does not.

[liorheber]

And just to clarify, I see that you can provide the schema but the hope is to parse it from the annotated type.

[awsarron]

Hi Lior, sorry for the misunderstanding, let me re-open this issue.

In the meantime, does this help - strands-agents/docs#236.

@tool(
    inputSchema={
        "json": {
            "type": "object",
            "properties": {
                "shape": {
                    "type": "string",
                    "enum": ["circle", "rectangle"],
                    "description": "The shape type"
                },
                "radius": {"type": "number", "description": "Radius for circle"},
                "width": {"type": "number", "description": "Width for rectangle"},
                "height": {"type": "number", "description": "Height for rectangle"}
            },
            "required": ["shape"]
        }
    }
)
def calculate_area(shape: str, radius: float = None, width: float = None, height: float = None) -> float:
    """Calculate area of a shape."""
    if shape == "circle":
        return 3.14159 * radius ** 2
    elif shape == "rectangle":
        return width * height
    return 0.0

The inputSchema can be overridden as you mentioned. We can consider supporting typing.Annotated too.

[liorheber]

Hi,

While adding the input schema or inserting the description into the Docstring are workarounds, they aren't very maintainable.

Our use case is we created types for our DTOs using pydantic.
This means duplicating them manually for our tools, or creating a pydantic converter specifically for InputSchema.

Supporting pydantic json schema by just passing the typed arguments in the method signature would go a long way.

Thanks again!