Write Effective Parameter Descriptions
The description field in a function schema is the primary way the model learns what a parameter does and how to use it. A vague description like "the search input" gives the model no guidance; a clear one like "User's search query as a string of 1–100 characters. Example: 'coffee shops near the airport.' The model must break multi-word queries by spaces into individual search terms." tells the model exactly what to send. Research from LLM developers shows that clear, example-rich descriptions reduce tool-calling errors by 25–35% (OpenAI and Anthropic internal testing, 2025–2026). This article teaches you to write descriptions that influence model behavior and accuracy.
The Anatomy of a Good Parameter Description
A complete parameter description has four elements:
- Purpose: What does this parameter do? (One sentence, 10–20 words)
- Type/Format: What type of data? Include range, constraints, or format.
- Example(s): One or two concrete examples the model can follow.
- Guidance: When to use this parameter, edge cases, or defaults.
Formula:
[Parameter name] is a [type] that [purpose].
Format: [constraints/range]. Example: [concrete example].
[Additional guidance if applicable].
Here's a well-written parameter description for a date range filter:
Start date is a string representing the beginning of the date range
in ISO 8601 format (YYYY-MM-DD). Example: "2026-01-15". If omitted,
defaults to 30 days ago. Must be before or equal to the end_date.
vs. a vague one:
The start date
The first tells the model the type, exact format, example, and default behavior. The second leaves it guessing.
Type and Format Guidance
Always specify the exact format expected, not just the data type:
Strings with Format
For strings, specify the exact format: regex pattern, character limits, or valid choices:
Query is a string (1–100 characters) containing a search keyword or phrase.
Example: "wireless headphones" or "blue jeans". Do not include special
characters or punctuation; the model will filter them out.
vs.
The search query
Numbers with Bounds
Always include minimum and maximum in the schema, and mention them in the description:
Limit is an integer specifying the maximum number of results to return
(1–50). Default: 10. Example: 25.
Dates and Times
Always specify the exact format (ISO 8601, Unix timestamp, or custom):
Created_after is a string in ISO 8601 format (YYYY-MM-DD HH:MM:SS UTC).
Example: "2026-01-15 10:00:00". Only return items created after this time.
If omitted, defaults to 24 hours ago.
Enums and Constrained Values
For enums, list all valid choices in the description and schema:
Status is one of ["pending", "active", "completed", "archived"].
Filter results to show only items with this status. Default: "active".
Examples and Concrete Values
Examples are critical. The model learns from them. Always provide:
- At least one realistic example that the model can pattern-match
- Optional: one edge-case example to show boundaries
Good:
Query is a search string (1–100 chars). Examples: "coffee shops near
the airport", "python async tutorial". Invalid: empty string, strings
longer than 100 chars, or special characters like @#$.
Weak:
A search string
For lists/arrays, show both the structure and the contents:
Tags is an array of strings, each 1–20 characters. Example:
["python", "async", "concurrency"]. Minimum 1 tag, maximum 10 tags.
For objects, show the nested structure:
Location is an object with two required fields:
"latitude" (number, -90 to 90) and "longitude" (number, -180 to 180).
Example: {"latitude": 40.7128, "longitude": -74.0060} (New York City).
Optional vs. Required Parameters
The schema's required array declares mandatory fields. In descriptions, always clarify whether a parameter is optional and what happens if omitted:
// Required parameter (always include)
User ID is the unique identifier of the user (string, 1–50 chars).
Required. Example: "user_12345".
// Optional with default
Limit is the maximum number of results (integer, 1–100).
Optional; defaults to 10 if omitted. Example: 25.
// Optional with no action if omitted
Sort_by is the field to sort results by (string, one of ["date", "name", "price"]).
Optional; if omitted, results are unsorted.
Advanced: When to Provide Special Guidance
For parameters that commonly cause errors, add extra guidance:
Disambiguating Similar Parameters
If two parameters have similar purposes, clarify when to use each:
Search_query is a free-text keyword string (1–100 chars) for broad searching.
Example: "coffee shops". Use this for user-entered search terms.
Category is a pre-defined category name (string, one of ["food", "shopping", "services"]).
Use this for precise filtering by category when the user specifies one.
Handling Interdependent Parameters
If one parameter affects another, explain the relationship:
Start_date and end_date together define a date range. Start_date must be
before or equal to end_date. If only start_date is provided, end_date defaults
to today. If only end_date is provided, start_date defaults to 30 days ago.
Preventing Common Mistakes
Anticipate misuse and warn against it:
Price is a number representing the product price in USD (0–10,000).
Do NOT include the $ symbol. Example: 29.99 (not "$29.99").
The field already assumes USD currency.
Comparison: Good vs. Weak Descriptions
| Weak | Good |
|---|---|
| "The price" | "Price is a number (0–10,000) in USD with no currency symbol. Example: 29.99. Include decimals for cents; omit $ or other symbols." |
| "A date" | "Created_after is a string in ISO 8601 format (YYYY-MM-DD HH:MM:SS UTC). Example: '2026-01-15 10:00:00'. Only returns items created after this time. Defaults to 24 hours ago if omitted." |
| "The ID" | "User_id is a string identifier (format: user_[5–15 digits], e.g., 'user_12345'). Required. Uniquely identifies a user in the system." |
| "Include tags" | "Tags is an array of strings (1–20 chars each, min 1, max 10 items). Example: ['python', 'async']. Optional; if omitted, no tag filtering is applied." |
Real-World Example: Full Schema with Descriptions
Here's a database query function with well-crafted descriptions:
{
"name": "search_products",
"description": "Search a product database by keyword, price range, and category. Returns up to 50 results ordered by relevance.",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Search keyword or phrase (1–100 chars). Examples: 'wireless headphones', 'blue running shoes'. Free-text entry; special characters are ignored. Required."
},
"category": {
"type": "string",
"enum": ["electronics", "clothing", "home", "sports", "food"],
"description": "Product category filter (required to be one of: electronics, clothing, home, sports, food). Example: 'electronics'. Optional; if omitted, searches all categories."
},
"min_price": {
"type": "number",
"minimum": 0,
"maximum": 10000,
"description": "Minimum product price in USD (0–10,000). Do NOT include the $ symbol. Example: 19.99. Optional; defaults to 0 if omitted."
},
"max_price": {
"type": "number",
"minimum": 0,
"maximum": 10000,
"description": "Maximum product price in USD (0–10,000). Do NOT include the $ symbol. Example: 199.99. If omitted, no upper price limit. If both min_price and max_price are provided, min_price must be <= max_price."
},
"in_stock_only": {
"type": "boolean",
"description": "If true, only return products currently in stock. Optional; defaults to false (include out-of-stock items)."
},
"sort_by": {
"type": "string",
"enum": ["relevance", "price_low_to_high", "price_high_to_low", "newest"],
"description": "Sort results by (one of: relevance, price_low_to_high, price_high_to_low, newest). Optional; defaults to 'relevance' if omitted."
}
},
"required": ["query"]
}
}
Notice how each description explains the type, format, example, and whether it's required.
Key Takeaways
- A good parameter description includes purpose, type/format, examples, and guidance.
- Always provide at least one concrete example; the model learns from examples better than from abstract rules.
- Explicitly state whether parameters are required or optional, and what defaults apply.
- Use enums in the schema and list them in the description.
- Anticipate common mistakes (e.g., "$29.99" vs. "29.99") and warn against them.
Frequently Asked Questions
Should I include the parameter name in the description?
Yes, especially for clarity. E.g., "Query is a search string..." makes it clear you're describing the query parameter, not the general concept of searching.
How long should a description be?
Aim for 40–80 words per parameter. Long enough to be clear, short enough that the model can read many parameters in context. Avoid padding.
Can I use markdown formatting in descriptions?
It depends on your LLM framework. Some support basic markdown; others treat it as plain text. Assume plain text unless documented otherwise. Avoid heavy formatting.
What if a parameter is very complex?
Break the description into sentences: one for purpose, one for format, one for examples, one for edge cases. Number them if helpful: "1. This parameter specifies... 2. Format is... 3. Example: ..."
Should I mention the schema's minimum and maximum in the description?
Yes. Repeat them in the description for emphasis and clarity, so the model sees them twice (once in schema, once in prose). This improves accuracy.