What is a tool schema, and why does the model need one?

Updated October 2026 · How we answer

Short answerA tool schema is a structured description of a function's name, purpose and parameters. The model reads it to decide whether to call the tool and what arguments to send.

Parts of a tool schema

A schema usually includes a name, a short description and a set of parameters with their types. Each parameter can have its own description and a list of allowed values. Required fields tell the model which inputs cannot be left out.

Clear descriptions matter more than many people expect. A vague description such as 'get data' gives the model little reason to choose the tool, while a specific description tells it exactly when the tool helps.

Why the model relies on names

The model does not run your function. It reads the schema, writes a structured request and returns that request to your code. Your code then runs the real function and sends the result back. Because the model works from text, the names and descriptions carry much of the decision.

Keep names short and literal. A tool called search_orders_by_email is easier to choose correctly than one called process_data.

  • Name each tool after a single clear action.
  • Describe when to use the tool and when not to.
  • Mark required parameters as required.
  • Use enums for fixed choices.

Common mistakes

  • Writing vague descriptions that hide what the tool actually does.
  • Assuming the model runs the function directly instead of returning a request for your code to execute.
From our shopsCaseMorph: Type an idea, see a custom phone case in seconds, then print a one-of-one.