14 個 AI Agent 框架工具 Schema 比較:只有 5 個預設將參數描述寫入 JSON Schema
AI Agent Framework Tool Schemas Compared: Only 5 of 14 Put Your Docstring Arg Descriptions in the Schema (Nov 2026)
Sarath Kavuru 以同一個附有 Google 風格 docstring 的 Python 函數,比較 14 個 AI Agent 框架於 2026-11-21 預設生成的工具定義;只有 5 個把六項參數描述寫入 JSON Schema,8 個將 Args 區塊留在工具描述中,AutoGen 則以參數名稱代替描述。
I passed one Python function with a Google-style docstring to 14 Python AI agent frameworks. Only 5 put the six parameter descriptions into the JSON Schema by default, 8 left them as raw docstring text inside the tool description, AutoGen described each parameter with its own name, and the emitted tool definitions ranged from 178 to 301 tokens.
Every agent framework advertises "just decorate your function." What the decorator actually sends to the model is rarely shown. That JSON is part of the prompt on every turn, and it decides whether max_price_usd arrives with a description, a type the model can satisfy, and a sensible required list.
So the research question was: given an identical, well-documented Python tool, what tool definition does each major agent framework generate by default, and how much do those definitions differ in structure and token cost?
How was the tool schema test run?
One function, 14 frameworks, default settings, run on November 21, 2026.
-
Test function:
search_flights(origin: str, destination: str, depart_date: str, max_price_usd: Optional[float] = None, cabin: Literal["economy", "premium", "business"] = "economy", nonstop_only: bool = False) -> str, with a one-line summary and a Google-styleArgs:block describing all six parameters. Three parameters are required, three have defaults. - Frameworks and versions: openai-agents 0.25.0, pydantic-ai 2.71.0, langchain-core 1.8.4 (LangChain/LangGraph), crewai 1.15.44, smolagents 1.26.0, google-adk 2.15.0, strands-agents 1.65.0, agno 3.2.1, llama-index-core 0.14.26, haystack-ai 3.5.0, autogen-core 0.7.5, agent-framework 1.26.0 (Microsoft Agent Framework), dspy 3.5.0, ag2 1.3.3. Each lives in its own virtualenv, installed from PyPI on November 20.
-
Extraction: each framework's documented one-line wrapper (
function_tool,Tool,@tool,FunctionTool,create_tool_from_function,Function.from_callable,dspy.Tool), then the object the framework hands to the model client: the OpenAI-format function for most; CrewAI's ownconvert_tools_to_openai_schema; ADK'sparameters_json_schemadeclaration; Strands'tool_spec. -
Token count: tiktoken
o200k_baseover compact JSON of{name, description, parameters}plusstrictwhere the framework sets it. -
Limitations: one function, so the absolute numbers apply to this function only. The token count is a proxy. Providers wrap tool JSON in their own template, and Claude and Gemini use different tokenizers. I tested defaults only; most frameworks have an opt-in for per-parameter docs (
Annotated,Field(description=...),parse_docstring=True). I did not test whether the differences change model accuracy.
What did each framework generate?
The same six parameters came out in at least five structurally different shapes.
| Framework (version) | Tokens | Param docs in schema |
title keys |
Required | Notable default |
|---|---|---|---|---|---|
| Agno 3.2.1 | 178 | 6/6 | 0 | 3 |
additionalProperties: false; drops null from max_price_usd
|
| smolagents 1.26.0 | 185 | 6/6 | 0 | 3 | OpenAPI-style nullable: true on all three optional params |
| Strands Agents 1.65.0 | 185 | 6/6 | 0 | 3 |
max_price_usd is type: number with default: null
|
| AutoGen (autogen-core 0.7.5) | 186 | 0/6 | 6 | 3 | each param's description is its own name ("origin": "origin") |
| Pydantic AI 2.71.0 | 199 | 6/6 | 0 | 3 |
additionalProperties: false, no titles |
LangChain @tool 1.8.4 |
213 | 0/6 | 0 | 3 | whole Args: block pasted into description |
| Haystack 3.5.0 | 215 | 0/6 | 0 | 3 | whole Args: block in description |
| DSPy 3.5.0 | 215 | 0/6 | 0 | 3 | whole Args: block in description |
| AG2 1.3.3 | 247 | 0/6 | 6 | 3 | docstring in description, Pydantic titles |
| OpenAI Agents SDK 0.25.0 | 249 | 6/6 | 7 | 6 |
strict: true; all six params required |
| Google ADK 2.15.0 | 252 | 0/6 | 7 | 3 | docstring in description, Pydantic titles |
| Microsoft Agent Framework 1.26.0 | 254 | 0/6 | 7 | 3 | properties re-sorted alphabetically (cabin first) |
| CrewAI 1.15.44 | 268 | 0/6 | 6 | 6 |
strict: true, docstring in description, titles |
| LlamaIndex 0.14.26 | 301 | 0/6 | 6 | 3 | Python signature prepended to description |
LangChain with parse_docstring=True produced 6/6 parameter descriptions at 194 tokens, 19 fewer than its default.
The full spread is 178 to 301 tokens, 1.69x for the same function. LlamaIndex's first description line is the Python signature, search_flights(origin: str, ... ) -> str, which costs 55 tokens by itself.
Where do the parameter descriptions end up?
In most frameworks, they end up in the tool description as prose, not on the parameters.
The split:
-
Parsed into
properties.*.description(5): OpenAI Agents SDK, Pydantic AI, smolagents, Strands Agents, Agno. -
Left as raw
Args:text in the tool description (8): LangChain (default), CrewAI, Google ADK, LlamaIndex, Haystack, Microsoft Agent Framework, DSPy, AG2. -
Replaced (1): AutoGen. Its
FunctionTooltakes a requireddescriptionargument and does not read the docstring. Each parameter'sdescriptionis set to the parameter name.
The text in the description is still visible to the model, so this is not lost information for most of the eight. It is information in the wrong structure. Anything that works per parameter sees no docs: UIs that render a form from inputSchema, schema validators, MCP clients that show arguments for approval, and code that trims long tool descriptions to save tokens. If you later shorten the description, as some guides on cutting MCP tool-definition overhead suggest, the argument docs go with it.
It is also not cheaper. In LangChain, the docstring-in-description form costs 213 tokens and the parsed form costs 194. The Args: block repeats every parameter name a second time.
How much do Pydantic title keys cost?
Between 31 and 39 tokens per tool in this test, 11–17% of the full definition.
Seven of the 14 frameworks pass Pydantic's model_json_schema() through without removing the auto-generated "title": "Max Price Usd" keys. Removing only those keys and re-counting:
framework parameters tokens without titles saved
OpenAI Agents SDK 228 190 38
Google ADK 136 97 39
Microsoft AF 136 97 39
CrewAI 146 114 32
LlamaIndex 129 97 32
AG2 129 97 32
AutoGen 165 134 31
Titles carry nothing the property name does not already carry. Pydantic AI, smolagents, Strands, Agno, Haystack, DSPy and LangChain omit them.
Why do two frameworks mark every parameter required?
Because they emit OpenAI strict mode, which requires every property to be listed in required.
The OpenAI Agents SDK sets strict: true and additionalProperties: false, puts all six parameters in required, and keeps max_price_usd as anyOf [number, null]. The model must send null, a cabin and a boolean on every call. That is correct strict-mode behavior. It means a few extra output tokens per call, and your function receives explicit values instead of Python defaults. CrewAI's OpenAI converter does the same, but its schema still has no parameter descriptions, so you get strict typing without per-parameter docs.
Which schemas have quirks that can break a validator?
Two, both on the optional max_price_usd.
-
Strands Agents emits
"type": "number", "default": null. JSON Schema does not validate defaults, so most validators accept it. The schema still contradicts itself: the default is not a number. A model that copies the default and sendsnullproduces an argument that fails validation against the declared type. -
smolagents uses
nullable: true. That is an OpenAPI 3.0 keyword, not JSON Schema. Validators ignore unknown keywords, so for themcabinandnonstop_onlyare not nullable at all.
Agno takes the stricter route. It removes null and relies on max_price_usd not being required, which is valid and the smallest schema in the set.
How does this connect to MCP?
When a framework re-exports a tool over MCP, its schema becomes the server's inputSchema, and the spec now accepts nearly anything in that field.
The MCP six-month report from aiagentsinfo.com, an independent research lab and AI agent directory, read the 2026-07-28 revision this way: "Servers should return tools/list in a stable order, so a prompt cache can hit. inputSchema, outputSchema, and structuredContent are looser: any JSON Schema 2020-12 keyword." The same report has a chapter titled "Tool descriptions are part of the prompt."
Put those next to this test. A looser inputSchema means the protocol will not remove a title key, a nullable keyword or a Python signature for you. Those bytes ship as the framework generated them, on every turn, wherever your tool goes. Stable ordering helps caching only if the schema itself is stable. Microsoft Agent Framework's alphabetical sort is deterministic, so it is cache-safe, but the argument order no longer matches the function signature. Which frameworks expose MCP at all is tracked separately in the framework MCP and A2A support table.
What does a 123-token gap mean at agent scale?
Across 20 tools, it is about 2,460 input tokens per request. That number is arithmetic, not a measurement.
The figure scales the gap between Agno (178) and LlamaIndex (301) linearly. Real tools vary in length, so use your own tool list. To put a price on it, paste your actual tool JSON into the prompt and tool checker. For one three-tool support agent, the cost of agent tool JSON across models found the tool JSON was $0.5655 of a $3.042 30-day gpt-5 bill. That makes the schema the smaller line item next to output tokens, but one you pay on every turn. For whole-agent budgets, the AI agent cost calculator handles turns, models and output length.
What should you do with your framework's defaults?
Print the generated schema once, before you trust the decorator.
-
Dump it. Every framework exposes the object; the extraction calls are in the method above. If the parameter descriptions are not under
properties, fix that first. -
Opt in to parsed docs where the framework offers it: LangChain
parse_docstring=True,Annotated[str, "..."]for AutoGen,Field(description=...)for Pydantic-based wrappers. -
Strip
titlekeys in a post-processor if your framework passes them through. That saved 31–39 tokens per tool here. -
Check optional types.
Optional[float]should come out asanyOf [number, null]or as a non-required plainnumber, not as a non-nullable type with anulldefault.
Framework choice is usually made on orchestration features. The comparison of AI agent frameworks covers those. Tool-schema generation is a smaller axis, but you pay for it on every request.
Data: 14 framework tool definitions generated on the box from PyPI releases installed November 20, 2026, extracted and counted November 21, 2026 with tiktoken o200k_base.
Sarath is the founder of aiagentsinfo.com, the research lab and directory for AI agents.
This article was written with AI assistance and reviewed for accuracy.
來源:DEV Community · dev.to