Designing a Tool-Calling Schema for a Search Tool
How to shape a search function's parameters and return type so an LLM uses it reliably.
How it works
Most function-calling frameworks expect a JSON Schema describing the tool's parameters, and the model uses the parameter names and descriptions — not just the tool name — to decide when and how to call it. A search tool typically needs at minimum a `query` string, but real-world schemas benefit from an optional `num_results` and a `recency` or `date_range` hint so the model can signal when it needs fresh results versus general background.
Example
A minimal but effective schema: {name: "web_search", parameters: {query: {type: "string", description: "A concise search query, not a full sentence"}, num_results: {type: "integer", default: 5}}}. The description field matters more than it looks — a vague description like 'searches the web' produces worse query construction from the model than one that explicitly says to avoid full natural-language sentences.
Pitfalls
- Overly permissive schemas (accepting any free-form string) lead models to pass entire user questions as the query instead of distilling them into effective search terms.
- Omitting a result-count cap means a verbose model sometimes requests far more results than it needs, wasting tokens and API quota.
- Not returning a consistent shape on empty results (sometimes an empty array, sometimes null, sometimes an error object) causes models to mishandle the no-results case inconsistently across turns.