Allow RunContext to not be documented when require_parameter_descriptions=True as it's not passed to the model anyway

[Kevsnz]

This PR refines the behavior of the require_parameter_descriptions=True argument in the @agent.tool and @agent.tool_plain decorators to be more permissive and robust. Previously, this setting exhibited incorrect behavior by raising errors in scenarios where docstrings either omitted descriptions for the RunContext parameter or included descriptions for parameters not present in the function signature. The latter case was particularly problematic as the error message incorrectly indicated missing descriptions when the issue was the presence of descriptions for non-existent parameters.

With this change, the following is now allowed when require_parameter_descriptions=True:

• Ignoring RunContext Descriptions: The docstring of a tool function can now omit a description for the RunContext parameter. Since RunContext is not typically a parameter directly consumed by the agent's logic, requiring its description was often unnecessary and could clutter docstrings.
• Silently Ignoring Descriptions for Non-Existent Parameters: Docstrings can now contain descriptions for parameters that do not exist in the function definition. Previously, this scenario would trigger a misleading error message ("Missing parameter descriptions for"). Now, these descriptions are silently ignored during validation, preventing unnecessary errors and providing more flexibility when maintaining docstrings during code refactoring.

Examples:

@agent.tool(require_parameter_descriptions=True)
def add_task(ctx: RunContext[TaskList], description: str) -> Task:
    """Adds a task to the list and returns it.

    :param description: The short description of the task.
    :return: The task that was added.
    """
    return ctx.deps.add_task(description)

Before this PR, with require_parameter_descriptions=True, an error would be raised because the docstring lacked a description for the ctx parameter. This is now allowed, streamlining docstrings for tools utilizing RunContext.

Next, consider a function with a parameter description that doesn't match a function parameter:

@agent.tool_plain(require_parameter_descriptions=True)
def get_time() -> datetime.time:
    """Returns the current time

    :param tz: Timezone
    :return: The current time of the day
    """
    return datetime.datetime.now().time()

Before this fix, the presence of the :param tz: in the docstring would incorrectly trigger the error message:

Missing parameter descriptions for

This was misleading because the issue wasn't a missing description, but rather the presence of a description for a non-existent parameter. Now, the description for the non-existent tz parameter is correctly and silently ignored, and no error is raised.

P.S. Yes, Gemini helped me rewrite and refine this description. However, I encountered the issues described above and made necessary changes in the code myself. Hope you'll find them helpful.

[DouweM]

@Kevsnz Thanks! The first change (ctx) makes sense, but in the second case, wouldn't we want to complain if the description lists an argument that doesn't actually exist? Including it could confuse the model.

[Kevsnz]

@Kevsnz Thanks! The first change (ctx) makes sense, but in the second case, wouldn't we want to complain if the description lists an argument that doesn't actually exist? Including it could confuse the model.

Good question. Intuitively I thought that @agent.tool would discard descriptions of non-existent parameters simply because there would be no place to put those descriptions.

To make sure I understand it correctly I ran a quick test with OTLP.
The following tool in the code:

@agent.tool_plain(require_parameter_descriptions=True)
def get_time() -> datetime.time:
    """Returns the current time

    :param bla: That is an unknown parameter!
    :return: The current time of the day
    """
    return datetime.datetime.now().time()

produced this tool in the request to the LLM provider:

{
	"tools": [
		{
			"type": "function",
			"function": {
				"name": "get_time",
				"description": "<summary>Returns the current time</summary>\n<returns>\n<description>The current time of the day</description>\n</returns>",
				"parameters": {
					"additionalProperties": false,
					"properties": {},
					"type": "object"
				}
			}
		}
	]
}

Sure enough, properties field is empty and there is no description of non-existent parameter bla.

So it looks like redundant params in docstrings could be safely ignored.