JSON Schema for tools

📝 Study Notes: JSON Schema for Tool Use

**I. Core Concepts**

• JSON Schema Definition: A general-purpose technique for data validation, not exclusive to LLMs or tool use.
• Purpose in Tool Use: The JSON schema describes the function (tool) and specifically details the arguments (parameters) the function expects.
• Function: It is sent in the request to the LLM (e. g. , Claude) to help the model understand how and when to use the defined function.

**II. The 4-Step Process for Creating a JSON Schema**

This process converts a function's arguments into a structured schema:

• Create Argument Dictionary: Write a dictionary containing all keyword arguments for the function, including sample data for each.
• Convert to JSON: Convert the dictionary into a JSON string.
• Note: Ensure Python data types are correctly converted (e. g. , Python's True becomes JSON's lowercase true).
• Generate Schema: Use a "JSON to JSON schema converter" tool (e. g. , online converters) to automatically generate the schema based on the JSON data.
• Action: Remove the initial dollar sign schema statement from the output.
• Add Descriptions: Add detailed descriptions to every property (argument) within the schema.

**III. Best Practices for Descriptions**

• Overall Tool Description:
• Must explain exactly what the tool does.
• Must explain when Claude should use the tool.
• Must explain what kind of data the tool returns.
• Goal: Aim for a description of three to four sentences.
• Argument Descriptions:
• Must be detailed.
• Must describe exactly what the argument does.
• Must explain how the argument fits into the overall tool use.
• Tip: If struggling to write descriptions, copy the function code and ask the LLM to write the descriptions for you.

**IV. Next Step**

• Once the JSON schema is complete, the next step is to call the LLM and include the schema so that the model is aware of the available tool.

Takeaways

• JSON Schema is a general-purpose data validation technique used to describe a function's parameters for LLMs.
• The process involves converting a function's arguments into a JSON string and then using a converter to generate the structured schema.
• Detailed descriptions are critical: the overall tool description must explain what the tool does and when to use it, while argument descriptions must explain their specific function.
• The final step is including the complete JSON schema in the request to the LLM so the model is aware of the available tool.