Heuristic:Mistralai Client python Tool Docstring Requirement
| Knowledge Sources | |
|---|---|
| Domains | Agents, Function_Calling |
| Last Updated | 2026-02-15 14:00 GMT |
Overview
Functions used as tools must have Google-style docstrings for accurate JSON Schema generation; missing docstrings produce degraded tool definitions.
Description
The Mistral Agents framework automatically generates JSON Schema tool definitions from Python function signatures and docstrings. The `create_tool_call()` function uses the griffe library to parse Google-style docstrings and extract function descriptions and parameter documentation. Without proper docstrings, the generated tool schemas lack descriptions, which degrades the model's ability to understand when and how to call the function.
Usage
Apply this heuristic whenever defining Python functions as tools for Mistral agents or function calling. Every function exposed to the model should have a complete Google-style docstring including a description and parameter documentation.
The Insight (Rule of Thumb)
- Action: Add Google-style docstrings to all functions used as Mistral tools.
- Format: Use Google docstring style (parsed by `griffe` with `parser="google"`).
- Required sections:
- Brief description (first line)
- `Args:` section with parameter descriptions
- `Returns:` section (recommended)
- Strict mode: Tool schemas are generated with `strict=True`, enforcing strict JSON Schema validation.
- Trade-off: None. This is purely beneficial with no downside.
Reasoning
The SDK parses function metadata at runtime using `inspect.signature()` for type hints and `griffe.Docstring()` for descriptions. When a function lacks a docstring, the SDK emits a warning and generates a schema with empty descriptions. The model relies on these descriptions to determine:
- When to call the function (from the function description)
- What values to pass (from parameter descriptions)
Without descriptions, the model must infer intent purely from parameter names, which is unreliable.
Code Evidence
Warning for missing docstrings from `src/mistralai/extra/run/tools.py:152-156`:
doc = inspect.getdoc(func)
if not doc:
logger.warning(
f"Function '{name}' without a docstring is being parsed, add docstring for more accurate result."
)
docstring_sections = []
Warning for empty docstring sections from `src/mistralai/extra/run/tools.py:160-163`:
if len(docstring_sections) == 0:
logger.warning(
f"Function '{name}' has no relevant docstring sections, add docstring for more accurate result."
)
Strict schema enforcement from `src/mistralai/extra/run/tools.py:170-181`:
return FunctionTool(
function=Function(
name=name,
description=_get_function_description(docstring_sections),
parameters=_get_function_parameters(
docstring_sections=docstring_sections,
params_from_sig=params_from_sig,
type_hints=type_hints,
),
strict=True,
),
)
Google-style parsing from `src/mistralai/extra/run/tools.py:158-159`:
docstring = Docstring(doc, parser="google")
docstring_sections = docstring.parse(warnings=False)