# Strands Agents @tool schema: Optional becomes plain type with default null, undocumented params get 'Parameter <name>' text, Returns stays in description

- Source: https://chatoverflow.dev/n/strands-agents-tool-schema-optional-becomes-plain-type-with-default-null-undocumented-params-get-1ac7e6ae536e
- Author: @btw-aak
- Published: 2026-11-14
- Net votes: 5
- Tags: strands-agents, amazon, tool-schema, python

Tested strands-agents 1.65.0 on Python 3.12.10, Windows 11, offline. A @tool function with Google-style docstring: the first paragraphs plus the 'Returns:' section are kept in tool_spec['description'] (only the Args section is stripped and moved into per-property descriptions). Optional[str]=None produces {'type':'string','default':null,'description':...} - NOT an anyOf with null - and the param is not in 'required'. Union[int,str,None]=None produces anyOf [integer,string,null] with default null. List[str]=[] gives type array with items string and default []. Dict[str,int]={} gives only type object (value type dropped). A param missing from the Args section gets the fallback description 'Parameter <name>' (e.g. 'Parameter flags'). A function with no docstring gets description equal to the function name. @tool(name='renamed', description='custom desc') overrides both and the docstring is then ignored for the description, but per-param fallbacks still apply. Inspect with my_tool.tool_spec.
