Tool parameters lose descriptions from Annotated[...] and docstring Args sections
Nobody has claimed this yet.
Assessment
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Newbie friendliness
- 72/100
Research direction
Start at the @ai.tool implementation where get_type_hints(fn) builds the parameter schema, then trace how it reaches model_json_schema(). Check the existing schema-generation coverage, or add focused coverage, for Annotated Field descriptions, Google-style Args descriptions, Field precedence, and unchanged schemas when neither mechanism is used.
Written by the indexing model from the issue text.
Description
Problem
@ai.tool builds the parameter schema with get_type_hints(fn), which strips Annotated metadata. The most natural typed-tool patterns therefore produce undocumented arguments:
from typing import Annotated
from pydantic import Field
@ai.tool
async def get_weather(
city: Annotated[str, Field(description="City name")],
days: Annotated[int, Field(ge=1, le=7, description="Forecast length")] = 3,
) -> str:
"""Get the weather forecast.
Args:
city: City to forecast for.
"""
return "sunny"
Today neither the Field(description=...) nor the Args: entry for city reaches the JSON schema the model sees. Descriptions materially affect tool selection and argument quality, so this hurts most in exactly the multi-tool workspaces the agent loop targets.
Suggested behavior
- resolve hints with
get_type_hints(fn, include_extras=True)soFieldmetadata survives intomodel_json_schema()(pydantic already supports this; no new dependency) - additionally fill missing property descriptions from a Google-style
Args:docstring section, withFieldtaking precedence - schemas for tools that use neither mechanism stay byte-identical
Happy to take this one.
- Dominant language
- Python
- Stars
- 184
- Forks
- 23
- Avg merge
- 4d 8h
- Merged PRs (30d)
- 24
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from vercel-labs/ai-python
-
Difficulty 5/5 Over a week Newbie friendliness 25/100
vercel-labs/ai-python#299 ·
-
Difficulty 4/5 3-5 days Newbie friendliness 55/100
vercel-labs/ai-python#272 ·
-
Difficulty 5/5 Over a week Newbie friendliness 30/100
vercel-labs/ai-python#224 · 1 comment · 1 reaction ·
All issues in vercel-labs/ai-python
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
-
enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 74/100