How to Fix Common Mistakes When Making API Requests

Omitting required properties when defining tool or schema objects.

Schema Object Example (Correct):

movie_schema = {
  "type": "object",
  "properties": {
    "title": {"type": "string"},
    "director": {"type": "string"},
    "year": {"type": "integer"}
  },
  "required": ["title", "director", "year"],
  "additionalProperties": False
}

Schema Object Example (Wrong):

movie_schema = {
  "type": "object",
  "properties": {
    "title": {"type": "string"},
    "director": {"type": "string"},
    "year": {"type": "integer"}
  },
  "required": ["title", "year"],
  "additionalProperties": False
}

Tool Definition Example (Correct):

tools = [
  {
    "type": "function",
    "function": {
      "name": "calculate",
      "strict": True,
      "description": "A calculator tool that can perform basic arithmetic operations. Use this when you need to compute mathematical expressions or solve numerical problems.",
      "parameters": {
        "type": "object",
        "properties": {
          "expression": {
            "type": "string",
            "description": "The mathematical expression to evaluate"
          }
        },
        "required": ["expression"]
      }
    }
  }
]

Tool Definition Example (Wrong):

tools = [
  {
    "type": "function",
    "function": {
      "name": "calculate",
      "strict": True,
      "description": "A calculator tool that can perform basic arithmetic operations. Use this when you need to compute mathematical expressions or solve numerical problems.",
      "parameters": {
        "type": "object",
        "properties": {
          "expression": {
            "type": "string",
            "description": "The mathematical expression to evaluate"
          }
        }
      }
    }
  }
]

Failing to set strict: true in response_format or tool definitions when constrained decoding is required.

response_format Example (Correct)

response_format = {
  "type": "json_schema",
  "json_schema": {
    "name": "movie_schema",
    "strict": True,
    "schema": movie_schema
  }
}

response_format Example (Wrong)

response_format = {
  "type": "json_schema",
  "json_schema": {
    "name": "movie_schema",
    "schema": movie_schema
  }
}

Tool Definition Example (Correct)

tools = [
  {
    "type": "function",
    "function": {
      "name": "calculate",
      "strict": True,
      "description": "A calculator tool that can perform basic arithmetic operations. Use this when you need to compute mathematical expressions or solve numerical problems.",
      "parameters": {
        "type": "object",
        "properties": {
          "expression": {
            "type": "string",
            "description": "The mathematical expression to evaluate"
          }
        },
        "required": ["expression"]
      }
    }
  }
]

Tool Definition (Wrong)

tools = [
  {
    "type": "function",
    "function": {
      "name": "calculate",
      "description": "A calculator tool that can perform basic arithmetic operations. Use this when you need to compute mathematical expressions or solve numerical problems.",
      "parameters": {
        "type": "object",
        "properties": {
          "expression": {
            "type": "string",
            "description": "The mathematical expression to evaluate"
          }
        },
        "required": ["expression"]
      }
    }
  }
]

Attempting to use optional parameters without employing anyOf.

Example (Correct):

{
  "type": "object",
  "properties": {
    "recordId": {
      "anyOf": [
        { "type": "string" },
        { "type": "null" }
      ]
    }
  },
  "required": ["recordId"],
  "additionalProperties": false
}

Example (Wrong):

{
  "type": "object",
  "properties": {
    "recordId": { "type": ["string", "null"] }
  },
  "required": ["recordId"],
  "additionalProperties": false
}

Not setting additionalProperties to false when using constrained decoding.

Example (Correct):

{
  "type": "object",
  "properties": {
    "name": {"type": "string"},
    "age": {"type": "integer"}
  },
  "additionalProperties": false
}

Example (Wrong):

{
  "type": "object",
  "properties": {
    "name": {"type": "string"},
    "age": {"type": "integer"}
  }
}