{"title":"Exercise: Designing Tool Schemas","description":null,"content":"# Exercise 1: Write a Tool Schema the Model Can Use\n\nDesign the JSON Schema for a tool with several typed parameters, including an enum and a required field, then confirm the model fills it in correctly from a natural-language request.\n\nThe schema is the contract between your code and the model. A vague or loose schema produces malformed or ambiguous tool calls; a precise one, with clear descriptions, typed parameters, and enums for fixed choices, gets you arguments you can pass straight into your function. Designing schemas well is most of what makes tool use reliable.\n\n### Requirements\n\n- Define a `create_event` tool with parameters: `title` (string, required), `date` (string, required), and `priority` (enum of `low`, `medium`, `high`).\n- Write clear descriptions for the tool and each parameter.\n- Send a natural-language request and inspect the arguments the model produces.\n- Print the parsed arguments.\n\n\n**main.py**\n\n```python\nfrom openai import OpenAI\nimport json\n\nclient = OpenAI() # Uses OPENAI_API_KEY from environment\n\n# TODO: define a `create_event` tool schema with:\n# - title: string, required\n# - date: string, required\n# - priority: string enum of \"low\", \"medium\", \"high\"\n# Give the tool and each parameter a clear description.\ntools = []\n\nrequest = \"Schedule a high priority event called Launch Review on 2026-07-01.\"\n\n# TODO: call the model with the request and the tool, then parse and print\n# the arguments from the tool call\n```\n\n\n### Expected Output\n\nThe model maps the sentence onto your schema, picking the right enum value and field names.\n\n\n```plaintext\nTool: create_event\nArguments: {'title': 'Launch Review', 'date': '2026-07-01', 'priority': 'high'}\n```\n\n\n### Solution\n\n\n**main.py**\n\n```python\nfrom openai import OpenAI\nimport json\n\nclient = OpenAI()\n\ntools = [\n {\n \"type\": \"function\",\n \"function\": {\n \"name\": \"create_event\",\n \"description\": \"Create a calendar event.\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"title\": {\"type\": \"string\", \"description\": \"The event title.\"},\n \"date\": {\"type\": \"string\", \"description\": \"The event date in YYYY-MM-DD format.\"},\n \"priority\": {\n \"type\": \"string\",\n \"enum\": [\"low\", \"medium\", \"high\"],\n \"description\": \"The event priority.\",\n },\n },\n \"required\": [\"title\", \"date\"],\n },\n },\n }\n]\n\nrequest = \"Schedule a high priority event called Launch Review on 2026-07-01.\"\n\nresponse = client.chat.completions.create(\n model=\"gpt-5.5\",\n messages=[{\"role\": \"user\", \"content\": request}],\n tools=tools,\n)\n\ncall = response.choices[0].message.tool_calls[0]\nargs = json.loads(call.function.arguments)\nprint(f\"Tool: {call.function.name}\")\nprint(f\"Arguments: {args}\")\n```\n\n\nThe schema does three jobs at once: `type` tells the model what kind of value each field holds, `required` forces the must-have fields to appear, and `enum` restricts `priority` to a closed set so you never get a surprise value. The descriptions guide the model on what each field means, which matters most when a field is ambiguous. A function written against this schema can trust the arguments without defensive parsing, because the contract was enforced during generation.\n\n---\n\n# Exercise 2: Design a Schema with an Array and a Nested Object\n\nReal tool arguments are not flat. A calendar event has a list of attendees and a structured location. Design a schema with an `array` parameter and a nested `object` parameter, and confirm the model populates both correctly from one sentence. Nested schemas are where tool design gets real, and where a loose schema produces unusable arguments.\n\n### Requirements\n\n- Define a `create_event` tool with `title` (string), `attendees` (array of strings), and `location` (nested object with `name` and `room`).\n- Send a natural-language request mentioning multiple attendees and a structured location.\n- Parse and print the arguments the model produced.\n\n\n**main.py**\n\n```python\nfrom openai import OpenAI\nimport json\n\nclient = OpenAI() # Uses OPENAI_API_KEY from environment\n\n# TODO: define a \"create_event\" tool whose parameters include:\n# - title: string (required)\n# - attendees: array of strings\n# - location: a nested object with \"name\" (string) and \"room\" (string)\ntools = []\n\nrequest = \"Schedule a meeting called Sprint Planning with Alice and Bob in the Madrid building, room 4B.\"\n\n# TODO: call the model with the request and tool, then parse and print the arguments\n```\n\n\n### Expected Output\n\nThe model fills the array of attendees and the nested location object from the sentence.\n\n\n```plaintext\n{\n \"title\": \"Sprint Planning\",\n \"attendees\": [\"Alice\", \"Bob\"],\n \"location\": {\n \"name\": \"Madrid building\",\n \"room\": \"4B\"\n }\n}\n```\n\n\n### Solution\n\n\n**main.py**\n\n```python\nfrom openai import OpenAI\nimport json\n\nclient = OpenAI() # Uses OPENAI_API_KEY from environment\n\ntools = [\n {\n \"type\": \"function\",\n \"function\": {\n \"name\": \"create_event\",\n \"description\": \"Create a calendar event.\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"title\": {\"type\": \"string\"},\n \"attendees\": {\"type\": \"array\", \"items\": {\"type\": \"string\"}},\n \"location\": {\n \"type\": \"object\",\n \"properties\": {\"name\": {\"type\": \"string\"}, \"room\": {\"type\": \"string\"}},\n \"required\": [\"name\"],\n },\n },\n \"required\": [\"title\"],\n },\n },\n }\n]\n\nrequest = \"Schedule a meeting called Sprint Planning with Alice and Bob in the Madrid building, room 4B.\"\n\nresponse = client.chat.completions.create(\n model=\"gpt-5.5\",\n messages=[{\"role\": \"user\", \"content\": request}],\n tools=tools,\n)\nargs = json.loads(response.choices[0].message.tool_calls[0].function.arguments)\nprint(json.dumps(args, indent=2))\n```\n\n\nDeclaring `attendees` as an `array` with string `items` tells the model to return a list, not a comma-joined string, and the nested `location` object gives the room and building their own typed fields instead of one blob. The model maps the sentence onto this structure because the schema spells out the shape it must produce. A function written against this schema receives a ready-to-use list and dict, which is the payoff of designing the structure rather than parsing free text afterward.","pageType":"ai-engineering"}

Get Premium