Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

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

Abierto
  • ¿Algo no está bien?
#5,443 2 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

@Narendra02053 ya está trabajando en esto.

Desde el 27/10/2026.

Evaluación

Dificultad
3/5
Tiempo estimado
1-2 días
Aptitud para principiantes
58/100
Tipo de issue
Error
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
python
Área
ai, backend-api-design

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.

Lenguaje dominante
Python
Estrellas
30.4k
Forks
4.9k
Merge medio
15 h 56 min
PR fusionados (30 d)
117

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de openai/openai-agents-python

Todos los issues de openai/openai-agents-python

Issues similares

Más issues de Python

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.