Skip to content
C Codeloom
LLMs

LLM Function Schema Best Practices

How to design tool schemas that LLMs actually call correctly, with naming, description, and parameter patterns that survive real users and adversarial inputs.

·4 min read · By Codeloom
Intermediate 10 min read

What you'll learn

  • ✓How LLMs read your tool schemas
  • ✓Naming and description rules that improve accuracy
  • ✓Parameter shape patterns to avoid
  • ✓How to gate side-effects with confirmation tools
  • ✓How to evaluate schema quality systematically

Prerequisites

  • •Basic function calling experience

What and Why

A function schema is the contract you give the model: here are the tools, here is what they do, here is what arguments they take. The model uses this schema to decide whether to call a tool, which one, and with what arguments. Bad schemas produce bad calls. Good schemas feel like the model “just knows” what to do.

Schema design is one of the highest-leverage skills in LLM engineering because the model never sees your implementation, only your description.

Mental Model

Think of the schema as a prompt fragment that is concatenated into the system context. Every word of your description is a hint the model uses to disambiguate. The tool name and parameter names are read as semantic clues, not as opaque identifiers. A parameter named q tells the model nothing; a parameter named search_query_in_natural_english tells it almost everything.

The model is also pattern-matching against training data. Common names like get_weather, send_email, search_web light up strong priors. Idiosyncratic names without good descriptions force the model to guess.

Hands-on Example

Consider a tool that books a meeting. A naive schema looks like this: a function called book with parameters t, p, and d. The model will sometimes get it right and often hallucinate values.


+------------------------+         +------------------------+
|  Vague schema          |         |  Specific schema       |
|  book(t, p, d)         |         |  schedule_meeting(     |
|                        |         |    title, attendees,   |
|                        |         |    start_iso, duration)|
+------------------------+         +------------------------+
         |                                  |
         v                                  v
 model guesses types               model fills correctly
 wrong arg order                   ISO timestamps used
 misses required field             validation passes
         |                                  |
         v                                  v
 [ runtime error ]                 [ meeting booked ]
How schema clarity shapes the model's decision and argument quality

The improved schema adds: a verb-noun name, fully spelled parameters, explicit types and formats, a clear description for each field, and required vs optional flags. The model now has enough signal to behave deterministically.

Trade-offs

Verbose schemas cost tokens. Every description goes into every request, multiplied by every tool. With ten tools and rich descriptions you can easily spend a thousand tokens per call before the user has typed anything. For very high-volume endpoints this matters.

Tight enums improve reliability but reduce flexibility. If you constrain priority to low, medium, high, the model cannot pass urgent, even if the user said exactly that. The fix is usually a normalization step in your handler, not a looser enum.

Splitting one tool into many narrower tools improves accuracy but increases prompt length and makes the model’s tool-selection step harder. Combining tools into one with a mode parameter is the inverse trade-off. Neither extreme is universally right.

Practical Tips

Use verbs for function names and nouns for parameters. create_invoice is better than invoice; customer_email is better than email.

Write descriptions as if you are explaining the tool to a smart new teammate who has never seen your codebase. Include when to use the tool and when not to. The “when not to” half is what stops wrong-tool calls.

Prefer ISO 8601 for any date or time. Models output it reliably and your parser will not have to guess.

Always mark parameters as required or optional explicitly. Models default to filling optional fields with plausible-sounding nonsense if the schema is ambiguous.

For destructive actions, split into a prepare_x tool that returns a preview and a confirm_x tool that takes a token from the preview. The model is forced to surface the action to the user before it is executed.

Run a schema evaluation: feed twenty prompts, log the tool calls, and grade them. Tighten the descriptions of any tool that gets misused. Treat schemas as living artifacts.

Wrap-up

Function schemas are prompts in disguise. The same care you put into system prompts belongs in your tool descriptions and parameter names. Treat ambiguity as a bug, lean toward verbose and explicit, and validate every call before executing side effects. A well-designed schema makes a mediocre model behave well; a sloppy schema makes a frontier model look unreliable.

Related articles