@tool decorator should enable parse_docstring=True by default for better LLM function calling

[Kevin-McIsaac]

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

1. Google Gemini recommends including descriptions for all parameters in function calling schemas (OpenAPI 3.0.3 compliance)
2. Better LLM performance - LLMs make more accurate tool calls when they understand what each parameter means
3. Reduced MALFORMED_FUNCTION_CALL errors - Gemini in particular is more reliable with complete schemas
4. 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:

1. Add deprecation warning when parse_docstring is not explicitly set
2. 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.

[sydney-runkle]

Agreed and have always been surprised that this isn't the case :)

[falloficaruss]

Hey, I would like to work solving this issue.

[sydney-runkle]

Following up, I think changing this would be pretty breaking for folks bc we error if the docstring isn't a valid google style docstring :(