Update Function tools docs with usage of docstring_format and require_parameter_descriptions (#776)

Author: chris-dare

docs/tools.md

@@ -234,7 +234,7 @@ Function parameters are extracted from the function signature, and all parameter
 
 Even better, PydanticAI extracts the docstring from functions and (thanks to [griffe](https://mkdocstrings.github.io/griffe/)) extracts parameter descriptions from the docstring and adds them to the schema.
 
-[Griffe supports](https://mkdocstrings.github.io/griffe/reference/docstrings/#docstrings) extracting parameter descriptions from `google`, `numpy` and `sphinx` style docstrings, and PydanticAI will infer the format to use based on the docstring. We plan to add support in the future to explicitly set the style to use, and warn/error if not all parameters are documented; see [#59](https://github.com/pydantic/pydantic-ai/issues/59).
+[Griffe supports](https://mkdocstrings.github.io/griffe/reference/docstrings/#docstrings) extracting parameter descriptions from `google`, `numpy`, and `sphinx` style docstrings. PydanticAI will infer the format to use based on the docstring, but you can explicitly set it using [`docstring_format`][pydantic_ai.tools.DocstringFormat]. You can also enforce parameter requirements by setting `require_parameter_descriptions=True`. This will raise a [`UserError`][pydantic_ai.exceptions.UserError] if a parameter description is missing.
 
 To demonstrate a tool's schema, here we use [`FunctionModel`][pydantic_ai.models.function.FunctionModel] to print the schema a model would receive:
 
@@ -246,7 +246,7 @@ from pydantic_ai.models.function import AgentInfo, FunctionModel
 agent = Agent()
 
 
-@agent.tool_plain
+@agent.tool_plain(docstring_format='google', require_parameter_descriptions=True)
 def foobar(a: int, b: str, c: dict[str, list[float]]) -> str:
     """Get me foobar.