Last Updated: May 1, 2025
Tool Definition Structure
{"type":"function","function":{"name":"get_weather","description":"Get current weather for a city","parameters":{"type":"object","properties":{"city":{"type":"string","description":"City name, e.g. San Francisco"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["city"]}}}Complete OpenAI tool definition with name, description, and JSON Schema parameters
{"type":"function","function":{"name":"search_docs","description":"Search the knowledge base using semantic + keyword search","parameters":{...}}}Tool for RAG — search documentation by semantic query
{"type":"function","function":{"name":"send_email","description":"Send an email. ALWAYS confirm recipient before sending.","parameters":{...}}}Include behavioral instructions in the description
{"type":"function","function":{"name":"run_sql","description":"Execute a READ-ONLY SQL query against the reporting database. NEVER use for writes.","parameters":{...}}}Describe constraints and permissions in the description
strict=TrueEnforce strict JSON Schema validation — model output will exactly match schema
Making Function Calls
import openai; client = openai.OpenAI()Initialize OpenAI client (v1.x+)
response = client.chat.completions.create(model="gpt-4o",messages=messages,tools=tools,tool_choice="auto")Send prompt with tools — model decides if/when to call
tool_choice="required"Force the model to call a function (useful for structured extraction)
tool_choice={"type":"function","function":{"name":"get_weather"}}Force a specific function call
tool_choice="none"Disable function calling for this request
tool_call = response.choices[0].message.tool_calls[0]Extract the tool call from the response
import json; args = json.loads(tool_call.function.arguments)Parse the function arguments from JSON string
{"tool_call_id":tool_call.id,"role":"tool","content":json.dumps(result)}Return tool result in the conversation history
Parallel Function Calling
| Item | Description |
|---|---|
Automatic Parallel | GPT-4 and GPT-4o automatically issue parallel calls when multiple functions are needed |
Parallel Example | User: 'What's the weather in SF and NYC?' → Model issues 2 get_weather calls simultaneously |
Ordering | All parallel calls execute independently — don't depend on results from other parallel calls |
Parallel Limit | Model may issue up to 32 parallel tool calls in a single response |
Handling Results | Add all tool results as separate tool messages before the next API call |
Disabling Parallel | Set parallel_tool_calls=False in the request to force sequential calling |
Timeout Strategy | Set per-tool timeouts; aggregate all results before returning to the model |
Partial Failures | If one parallel call fails, return the error for that tool — let the model decide how to proceed |
Structured Outputs & Best Practices
| Item | Description |
|---|---|
JSON Mode | Use response_format={'type':'json_object'} for structured JSON (non-tool use) |
Strict Mode (new) | response_format with json_schema enforces exact output structure — better than JSON mode |
Describe Parameters Well | Vague parameter descriptions = model fills in wrong values. Be specific with examples |
Enum Over String | Use enum constraints for categorical values — prevents hallucinated options |
Meaningful Names | Function names should describe the action: search_docs is better than func_1 |
Handle Refusals | Model may decline to call a function. Check for content before tool_calls in the response |
Token Efficiency | Long function descriptions consume context tokens. Keep descriptions concise but complete |
Validation Layer | Always validate arguments server-side before executing — model may hallucinate parameters |
Pro Tip: Always include a clear 'purpose' in your function descriptions. Models use the description — not just the parameter names — to decide when to call a function.