Prefer Pydantic model docstrings for tool schema descriptions#57
Merged
JohnRichard4096 merged 3 commits intomainfrom Apr 25, 2026
Merged
Prefer Pydantic model docstrings for tool schema descriptions#57JohnRichard4096 merged 3 commits intomainfrom
JohnRichard4096 merged 3 commits intomainfrom
Conversation
Contributor
Reviewer's GuideAdds Pydantic model docstring handling for tool schemas, updates documentation with best practices and formatting fixes, and bumps the patch version. Sequence diagram for Pydantic model description resolution during tool schema generationsequenceDiagram
actor Developer
participant simple_tool
participant _python_type_to_property_schema
participant _convert_pydantic_model_to_property_schema
participant FunctionPropertySchema
Developer->>simple_tool: define tool(address: UserAddress)
simple_tool->>_python_type_to_property_schema: python_type=UserAddress, description="address param description" (optional)
_python_type_to_property_schema->>_python_type_to_property_schema: has_desc = bool(description)
alt python_type is Pydantic BaseModel
_python_type_to_property_schema->>_convert_pydantic_model_to_property_schema: model_class=UserAddress, desc=description if has_desc else None
_convert_pydantic_model_to_property_schema->>_convert_pydantic_model_to_property_schema: resolve description = model_class.__doc__ or desc or fallback
_convert_pydantic_model_to_property_schema-->>FunctionPropertySchema: create(type="object", description=resolved description, ...)
else other Python types
_python_type_to_property_schema-->>FunctionPropertySchema: create schema with description (or "No description")
end
FunctionPropertySchema-->>simple_tool: parameter schema with final description
simple_tool-->>Developer: registered tool with JSON Schema using Pydantic model docstring when available
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
Member
Author
|
@sourcery-ai title |
sourcery-ai
Bot
changed the title
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Hey - I've found 3 issues, and left some high level feedback:
- When using
model_class.__doc__as the schema description, consider stripping whitespace and handling empty/whitespace-only docstrings so you don't end up with blank descriptions (e.g.,desc = (model_class.__doc__ or '').strip() or desc or f'Pydantic model {model_class.__name__}'). - Several Markdown code fences in the docs were changed from language-tagged (e.g.,
python,xml) to bare ```/```` fences; if syntax highlighting is still desired, it would be better to keep the language tags while still resolving any nesting issues. - The changes to the
:::lines in the suspend guides (extra leading spaces before:::) may alter how callouts/admonitions render in your docs toolchain; double-check whether those spaces are necessary or should be removed to preserve the original layout.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- When using `model_class.__doc__` as the schema description, consider stripping whitespace and handling empty/whitespace-only docstrings so you don't end up with blank descriptions (e.g., `desc = (model_class.__doc__ or '').strip() or desc or f'Pydantic model {model_class.__name__}'`).
- Several Markdown code fences in the docs were changed from language-tagged (e.g., ```python, ```xml) to bare ```/```` fences; if syntax highlighting is still desired, it would be better to keep the language tags while still resolving any nesting issues.
- The changes to the `::: ` lines in the suspend guides (extra leading spaces before `:::`) may alter how callouts/admonitions render in your docs toolchain; double-check whether those spaces are necessary or should be removed to preserve the original layout.
## Individual Comments
### Comment 1
<location path="src/amrita_core/tools/manager.py" line_range="226-229" />
<code_context>
def _convert_pydantic_model_to_property_schema(
- model_class: type[BaseModel], globalns: dict[str, Any]
+ model_class: type[BaseModel], globalns: dict[str, Any], desc: str | None = None
) -> FunctionPropertySchema:
"""Convert a Pydantic model to FunctionPropertySchema recursively"""
</code_context>
<issue_to_address>
**suggestion:** Consider normalizing the model docstring before using it as the schema description.
Directly using `model_class.__doc__` can introduce leading/trailing whitespace or blank lines, depending on formatting. Consider normalizing it first, e.g. `(model_class.__doc__ or '').strip()`, before falling back to `desc` or the default so schema descriptions remain clean and consistent.
</issue_to_address>
### Comment 2
<location path="src/amrita_core/tools/manager.py" line_range="265-271" />
<code_context>
def _python_type_to_property_schema(
- python_type: Any, globalns: dict[str, Any], description: str = "No description"
+ python_type: Any,
+ globalns: dict[str, Any],
+ description: str | None = None,
) -> FunctionPropertySchema:
"""Convert Python type to FunctionPropertySchema with full JSON Schema support"""
# Handle basic types
+ has_desc = bool(description)
+ description = description or "No description"
if python_type is str:
</code_context>
<issue_to_address>
**question:** Empty-string descriptions are treated as missing and replaced with "No description"; clarify if this is intended.
Because `has_desc = bool(description)` and `description = description or "No description"`, an explicit empty-string description is treated the same as `None`: `has_desc` becomes `False`, the description is not forwarded to `_convert_pydantic_model_to_property_schema`, and it gets replaced with "No description". If you only need to distinguish `None` from "user provided", using `has_desc = description is not None` would keep explicit empty descriptions while still avoiding overriding model docstrings unless the caller supplies something.
</issue_to_address>
### Comment 3
<location path="docs/guide/concepts/suspend.md" line_range="318" />
<code_context>
- Need to process chunks but don't want to write manual loops? Use **callback mode**, start with `chat.begin()` then `await chat` to wait for completion.
- Need streaming output to terminal or WebSocket? Use **iterator mode** with the `async with chat:` context manager.
- Regardless of mode, outer suspension (`wait_to_suspend`) works normally.
-:::
+ :::
</code_context>
<issue_to_address>
**issue (bug_risk):** The added indentation before `:::` may break the intended block/admonition formatting.
This moved `:::` from column 0 to two-space indentation, which may stop the docs tooling from recognizing the block/admonition. If the change wasn’t intentional, please restore it to start at column 0.
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
Deploying amritacore with
|
| Latest commit: |
bf2e2f1
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://89c90037.amritacore.pages.dev |
| Branch Preview URL: | https://feat-tool-desc.amritacore.pages.dev |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary by Sourcery
Clarify how Pydantic model docstrings and field descriptions are used in JSON Schema generation and ensure tools schema generation prefers model-level descriptions, while updating docs and metadata accordingly.
New Features:
Enhancements:
Build:
Documentation: