@tool decorator should enable parse_docstring=True by default for better LLM function calling #34292
Description
Issue
The @tool decorator defaults to parse_docstring=False, which means parameter descriptions from docstrings are not included in the generated tool schema. This results in schemas that lack parameter-level descriptions, which degrades LLM function calling performance.
Current Behavior
from langchain_core.tools import tool
@tool
def search_knowledge_base(query: str, top_k: int = 5) -> str:
"""
Search the knowledge base for relevant documents.
Args:
query: Search query for the knowledge base
top_k: Number of results to return (1-10)
Returns:
Formatted search results
"""
return f"Results for: {query}"
# Generated schema - NO parameter descriptions!
print(search_knowledge_base.args_schema.model_json_schema())Output:
{
"properties": {
"query": {"title": "Query", "type": "string"},
"top_k": {"default": 5, "title": "Top K", "type": "integer"}
},
"required": ["query"],
"title": "search_knowledge_baseSchema",
"type": "object"
}Note: No description fields for parameters, despite having Google-style docstrings.
Expected Behavior
Parameter descriptions should be included by default:
{
"properties": {
"query": {
"title": "Query",
"type": "string",
"description": "Search query for the knowledge base"
},
"top_k": {
"default": 5,
"title": "Top K",
"type": "integer",
"description": "Number of results to return (1-10)"
}
},
...
}Why This Matters
- Google Gemini recommends including descriptions for all parameters in function calling schemas (OpenAPI 3.0.3 compliance)
- Better LLM performance - LLMs make more accurate tool calls when they understand what each parameter means
- Reduced MALFORMED_FUNCTION_CALL errors - Gemini in particular is more reliable with complete schemas
- Developer ergonomics - Docstrings are already written, they should be used
Current Workarounds
Option 1: Use parse_docstring=True
@tool(parse_docstring=True)
def search_knowledge_base(query: str, top_k: int = 5) -> str:
...Option 2: Use explicit args_schema
from pydantic import BaseModel, Field
class SearchInput(BaseModel):
query: str = Field(description="Search query for the knowledge base")
top_k: int = Field(default=5, description="Number of results to return")
@tool(args_schema=SearchInput)
def search_knowledge_base(query: str, top_k: int = 5) -> str:
...Both work, but Option 2 duplicates information already in the docstring.
Proposed Change
Change the default from parse_docstring=False to parse_docstring=True in the @tool decorator.
This is a breaking change for users who have malformed docstrings and rely on the current silent behavior. A migration path could be:
- Add deprecation warning when
parse_docstringis not explicitly set - Change default in a future major version
Related Issues
- bug raise error with parsing docstring - google style with type #26430 - Bug with parsing Google-style docstrings
- core: make docstring parsing more robust #28628 - Make docstring parsing more robust
- [Bug] Arg Returns in docstring not found in function signature. #26093 - "Arg Returns in docstring not found"
These issues suggest docstring parsing has edge cases, but the solution should be to fix parsing, not to disable it by default.