Skip to main content

Function Schema Design: Beginner's Guide

A function schema is a formal declaration of what a tool does, what inputs it accepts, and what data types those inputs must be. When you register a tool with an LLM, the schema is the metadata that tells the model "this function exists, here are its parameters and their meanings." The LLM reads that schema before deciding to call your tool, and uses it to construct valid function calls. A clear schema directly improves model accuracy: vague parameter names and missing descriptions lead to wrong arguments or missing required fields. Well-written schemas reduce tool-calling errors by 30–40% compared to minimal descriptions (based on internal testing at Anthropic and OpenAI, 2025–2026).

Why Schemas Matter for Tool Calling​

When an LLM decides to use a tool, it doesn't execute code—it generates a JSON object with the function name and arguments. That JSON must match the schema exactly, or your code will reject it. A schema serves three purposes:

  1. Guidance: The model reads the schema and learns which parameters are required, which are optional, and what each one does. Clear descriptions steer the model toward correct choices.
  2. Validation: Your application code parses the generated JSON against the schema, rejecting malformed or invalid calls before they reach your function.
  3. Documentation: The schema doubles as machine-readable API docs, so other developers (and code generators) know what your tool expects.

Consider a weather lookup function. Without a schema, the model might guess parameter names or miss required fields. With a schema like the one below, the model knows exactly what's expected:

{
  "name": "get_weather",
  "description": "Fetch current weather for a location",
  "parameters": {
    "type": "object",
    "properties": {
      "latitude": {
        "type": "number",
        "description": "Latitude of the location in degrees"
      },
      "longitude": {
        "type": "number",
        "description": "Longitude of the location in degrees"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "Temperature scale (default: celsius)"
      }
    },
    "required": ["latitude", "longitude"]
  }
}

The model sees that latitude and longitude are mandatory numbers, and unit is optional with only two valid choices. This specificity prevents errors.

The Anatomy of a Function Schema​

A complete function schema has five main parts:

Name and Description​

The name field is the function identifier (used when the model calls it) and must be a valid identifier (alphanumeric + underscores). The description field (100–200 words) explains what the function does and when to use it. Be specific: "Retrieves weather data for a given latitude/longitude in real-time using the National Weather Service API, updated every 10 minutes" is better than "Gets weather info."

Parameters Object​

The parameters section is always an object with type: "object", a properties map describing each parameter, and a required array listing mandatory parameters. Each property has:

  • type: the data type (string, number, integer, boolean, array, object)
  • description: a clear explanation (40–60 words) of what this parameter does
  • enum (optional): an array of allowed values
  • default (optional): the default value if not provided
  • Additional constraints like minLength, pattern, minimum, maximum

Required vs. Optional​

Parameters listed in required must always be present. Omit them to make a parameter optional. Always mark optional parameters in the description, e.g., "Optional; if omitted, uses the current location."

Type Safety​

Each parameter's type must match the data your function actually accepts. A mismatch causes runtime errors. For example, if your function expects an integer count but the schema says string, the model may send "5" instead of 5.

Defaults​

If a parameter is optional and has a sensible default, declare it with "default". This helps the model understand the consequence of omitting the parameter.

A Complete Example: Database Query Tool​

Here's a function schema for a tool that searches a product database:

{
    "name": "search_products",
    "description": "Search a product database by keyword, category, or price range. Returns up to 20 results ordered by relevance.",
    "parameters": {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "Search keyword or phrase (e.g., 'wireless headphones', 'blue shirt')"
            },
            "category": {
                "type": "string",
                "enum": ["electronics", "clothing", "home", "sports"],
                "description": "Product category filter. If omitted, searches all categories."
            },
            "min_price": {
                "type": "number",
                "description": "Minimum product price in USD. Optional; default is 0."
            },
            "max_price": {
                "type": "number",
                "description": "Maximum product price in USD. Optional; if not set, no upper limit."
            },
            "in_stock_only": {
                "type": "boolean",
                "description": "If true, only return products currently in stock. Default: false."
            }
        },
        "required": ["query"]
    }
}

Only query is mandatory. The model understands it should filter by category if the user mentions one, or include a price range if the user says "under $50." The enums for category prevent invalid choices.

Common Schema Mistakes to Avoid​

  1. Vague descriptions: "The time value" tells the model nothing. Say "Unix timestamp in seconds (e.g., 1609459200 for 2021-01-01 00:00:00 UTC)."
  2. Missing enums: If a parameter accepts only 3 valid values, list them. Don't expect the model to guess.
  3. Inconsistent types: If a parameter expects an integer count, declare type: "integer", not string. Type mismatches cause parsing errors.
  4. Ambiguous required fields: Always explicitly list required parameters. Never assume the model will infer this.
  5. No defaults for optional fields: If a field has a sensible default and is optional, document it so the model knows the consequence of omitting it.

Key Takeaways​

  • A function schema is a JSON specification that defines a tool's name, purpose, parameters, and types.
  • Clear, detailed schemas reduce tool-calling errors by 30–40% by guiding the model toward correct choices.
  • Schemas serve as guidance for the model, validation for your code, and documentation for developers.
  • Always include a clear description for the function and each parameter; specify required fields and data types precisely.
  • Use enum to restrict parameters to valid choices, and document defaults for optional parameters.

Frequently Asked Questions​

Do I need a schema for every function my LLM calls?​

Yes. Even for simple functions, a schema ensures the model sends correctly typed data. Without it, the model guesses and often gets parameter names or types wrong.

Can I skip parameters that the model never uses?​

No. Include all parameters your function accepts so the model has the option. If some are rarely used, mark them as optional and provide clear descriptions explaining when to use them.

What happens if the model sends a parameter that doesn't match the schema?​

Your application should validate the generated JSON against the schema and reject invalid calls. Standard JSON Schema validators (jsonschema in Python, Ajv in JavaScript) can do this automatically.

Should I include example values in the schema?​

Not in the JSON Schema specification itself, but you can provide examples in the tool description or in your prompt instructions to the model. Some frameworks support an optional examples field for this purpose.

How do I know if my descriptions are clear enough?​

Test with the LLM: ask it to use the tool in a specific scenario and see if it constructs the call correctly. If it misses parameters or sends wrong types, your descriptions need more detail or examples.

Further Reading​