Tool Schemas (Tools & JSON Schema)

1. Concept Overview & Systemic Problem

Imagine you invited a new assistant to the office and told them: “Here we have a special program, use it.” But you didn’t explain what the buttons do or what fields need to be filled. Naturally, the assistant would be confused.

To ensure the language model knows what digital tools it possesses, developers provide it with a Tool Schema.

This is a compact description structured according to the JSON Schema standard:

• Name: a short name for the button (e.g., book_hotel).
• Description: a human-readable explanation of the action's purpose.
• Parameters: the data required to execute (city, check-in date, number of guests).

Mental model: a job description for AI: a list of tools on the master’s belt with clear instructions on when to use a hammer and when to use a screwdriver.

2. How a Real Tool Schema Looks

{
  "name": "calculate_mortgage",
  "description": "Calculates the monthly payment for a mortgage loan.",
  "parameters": {
    "type": "object",
    "properties": {
      "loan_amount": {
        "type": "number",
        "description": "The total loan amount in currency, e.g., 1500000"
      },
      "years": {
        "type": "integer",
        "description": "The loan term in years from 1 to 30"
      },
      "interest_rate": {
        "type": "number",
        "description": "Annual interest rate in percentage, e.g., 7.5"
      }
    },
    "required": ["loan_amount", "years"]
  }
}

3. Four Golden Rules for Crafting a Good Schema

1. Write the description as if explaining to an intern: specify not only what the tool does but also when it should NOT be called.
2. Provide examples in the description field: “date format strictly YYYY-MM-DD, e.g., 2026-05-18”.
3. Limit options using enum: if the order status can only be one of three types, specify strictly: ["pending", "shipped", "delivered"].
4. Mark required fields in the required array: if the function cannot operate without the client's email, do not allow the model to run it blindly.

4. Production Engineering Scenarios

01. Tool Integration in a Chatbot

Integrate tool schemas into a chatbot framework to enhance user interactions. Ensure that the chatbot can dynamically call functions based on user input, leveraging the clarity of tool descriptions to minimize errors.

02. API Development with JSON Schema

Utilize JSON Schema to define API endpoints for your application. This ensures that all developers understand the expected input and output formats, reducing integration issues and improving collaboration.

03. Automated Testing of Tool Functions

Implement automated tests that validate the functionality of tools against their schemas. This will help catch discrepancies between the expected and actual behavior of functions, ensuring reliability in production.

5. Pitfalls, Common Mistakes & Security

• Ambiguous Descriptions: Vague descriptions can lead to misinterpretations by the model, causing incorrect function calls.
• Neglecting Required Fields: Failing to specify required fields can result in runtime errors when the model attempts to execute functions without necessary data.
• Inadequate Testing: Not validating tool schemas against real-world scenarios can lead to unexpected failures in production, undermining user trust and system reliability.