Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

function_tool on a callable object uses an inherited or generated class docstring as the tool description

Open
  • Is something wrong?
#5,443 2 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

@Narendra02053 is already working on this.

Since Oct 27, 2026.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
58/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
python
Domain
ai, backend-api-design

Research direction

Start with _normalize_function_tool_callable in src/agents/tool.py and generate_func_documentation in src/agents/function_schema.py; inspect how both obtain class docstrings and review test_callable_object_uses_call_docstring_when_class_docstring_missing in tests/test_function_tool_decorator.py. Add regression coverage for inherited stdlib and generated dataclass or NamedTuple docstrings, plus documented user base classes. Done when callable tool descriptions and summaries use the intended __call__ or user-written class documentation across those cases.

Written by the indexing model from the issue text.

Description

Please read this first
  • Have you read the docs? Yes
  • Have you searched for related issues? Yes. Callable-object tools and _normalize_function_tool_callable came from #3949. I didn't find anything about where a callable tool's class docstring comes from.
Describe the bug

For a callable object, _normalize_function_tool_callable reads the class docstring with inspect.getdoc(type(func)) (tool.py#L2609). When the class has no docstring of its own, inspect.getdoc falls back to the first base class that has one, and @dataclass and NamedTuple store generated text as __doc__. That text then takes priority over the __call__ docstring, so the description sent to the model is wrong:

  • a tool class whose undocumented abstract base derives from ABC gets the stdlib text "Helper class that provides a standard way to create an ABC using inheritance." (an undocumented typing.Generic or typing.Protocol base does the same with those classes' docstrings)
  • a @dataclass gets its constructor signature, including default values such as an internal base URL
  • a NamedTuple gets 'NamedTupleLookup(region,)'

A plain class with only a __call__ docstring works, which is what test_callable_object_uses_call_docstring_when_class_docstring_missing in tests/test_function_tool_decorator.py covers.

Debug information
  • Agents SDK version: 0.24.0, and current main (b040da59)
  • Related library versions: none
  • Python version: 3.12.7, plus 3.10.4 and 3.14.6 with the 0.24.0 wheel, same output
  • Operating system: macOS 26.6.2
  • Model and model provider: none needed, the description is wrong before any request is sent
  • Does the issue reproduce with the latest Agents SDK release? Yes
  • Does the issue occur consistently or intermittently? Consistently
WeatherLookup     'Helper class that provides a standard way to create an ABC using\ninheritance.'
DataclassLookup   "DataclassLookup(base_url: str = 'https://weather.internal.example', units: str = 'metric')"
NamedTupleLookup  'NamedTupleLookup(region,)'
Configured        'Look up the weather.'
Repro steps
from abc import ABC, abstractmethod
from dataclasses import dataclass
from typing import NamedTuple

from agents import function_tool


class WeatherTool(ABC):
    @abstractmethod
    async def __call__(self, city: str) -> str: ...


class WeatherLookup(WeatherTool):
    async def __call__(self, city: str) -> str:
        """Return the current weather for a city."""
        return f"sunny in {city}"


@dataclass
class DataclassLookup:
    base_url: str = "https://weather.internal.example"
    units: str = "metric"

    async def __call__(self, city: str) -> str:
        """Return the current weather for a city."""
        return f"sunny in {city}"


class NamedTupleLookup(NamedTuple):
    region: str = "us-east-1"

    async def __call__(self, city: str) -> str:
        """Return the current weather for a city."""
        return f"sunny in {city}"


class DocumentedBase:
    """Look up the weather.

    Args:
        city: The city to look up.
    """

    async def __call__(self, city: str) -> str:
        return f"sunny in {city}"


class Configured(DocumentedBase):
    pass


for obj in (WeatherLookup(), DataclassLookup(), NamedTupleLookup(), Configured()):
    print(f"{type(obj).__name__:17} {function_tool(obj).description!r}")
Expected behavior

The first three get 'Return the current weather for a city.'. The docstrings that stdlib bases like ABC, Generic and Protocol carry, and the text @dataclass and NamedTuple generate, weren't written for the tool and shouldn't become its description. Docstrings from the user's own classes should keep working as they do today, as Configured shows.

Suggested fix

Keep finding the class docstring through the MRO the way inspect.getdoc does, but skip two kinds of text: the docstrings of stdlib bases such as abc.ABC, typing.Generic and typing.Protocol, and text that @dataclass or NamedTuple generated. Generated text sits in the class's own __dict__ next to __dataclass_fields__ or _fields, and it starts with ClassName( (or is just ClassName when dataclasses can't build a signature on 3.11+), so a prefix check is enough. Rebuilding the string with inspect.signature(cls) doesn't reliably match on 3.14, which renders annotations with annotation_format=FORWARDREF. Docstrings from the user's own base classes and mixins would keep being used, as today.

The class summary needs the same source. When both docstrings exist, the description comes from generate_func_documentation(type(func), ...) at L2613, which calls inspect.getdoc again (function_schema.py#L260). For example, a @dataclass subclass of a documented base whose __call__ has a docstring gets "ConfiguredDataclass(units: str = 'metric')" as its description, and changing only L2609 wouldn't fix that.

Dominant language
Python
Stars
30.4k
Forks
4.9k
Avg merge
14h 33m
Merged PRs (30d)
142

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from openai/openai-agents-python

All issues in openai/openai-agents-python

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.