Prompt Engineering

This page adapts the original AI SDK documentation: Prompt Engineering.

Prompt Engineering

Tips

Prompts for Tools

When you create prompts that include tools, getting good results can be tricky as the number and complexity of your tools increases.

Here are a few tips to help you get the best results:

1. Use a model that is strong at tool calling, such as gpt-4 or gpt-4.1. Weaker models will often struggle to call tools effectively and flawlessly.
2. Keep the number of tools low, e.g. to 5 or less.
3. Keep the complexity of the tool parameters low. Complex JSON schemas with many nested and optional elements, unions, etc. can be challenging for the model to work with.
4. Use semantically meaningful names for your tools, parameters, parameter properties, etc. The more information you pass to the model, the better it can understand what you want.
5. Add descriptive metadata to your JSON schema properties (for example a "description" field) to give the model hints about what each property is for.
6. When the output of a tool might be unclear to the model and there are dependencies between tools, use the description field of a tool to provide information about the output of the tool execution.
7. You can include example input/outputs of tool calls in your prompt to help the model understand how to use the tools. Keep in mind that the tools work with JSON objects, so the examples should use JSON.

In general, the goal should be to give the model all information it needs in a clear way.

Tool & Structured Data Schemas

The mapping from Swift schemas (for example using schema: MyCodableType.self or falling back to FlexibleSchema<MyType>.jsonSchema(...)) to the JSON that an LLM consumes is not always straightforward, since the mapping is not one-to-one.

Date Handling

Models return dates as strings. Specify the format in the schema and convert the string to a Date after generation (or configure a decoder when using Schema.codable).

import SwiftAISDK
import OpenAIProvider

struct Event: Decodable {
  let event: String
  let date: Date
}

struct EventsResponse: Decodable {
  let events: [Event]
}

let result = try await generateObject(
  model: openai("gpt-4.1"),
  schema: EventsResponse.self,
  schemaName: "events",
  prompt: "List 5 important events from the year 2000."
)

let events = result.object.events

Optional Parameters

When working with tools that have optional parameters, you may encounter compatibility issues with certain providers that use strict schema validation.

Note This is particularly relevant for OpenAI models with structured outputs (strict mode).

For maximum compatibility, optional parameters should be marked as nullable instead of omitting them entirely. When you rely on typed tools the Swift port marks String? or Int? properties as nullable in the generated schema, so providers like OpenAI accept them:

import SwiftAISDK

struct ExecuteCommandInput: Codable, Sendable {
  let command: String
  let workdir: String?
  let timeout: String?
}

struct CommandResult: Codable, Sendable {
  let status: String
}

let executeCommand = tool(
  description: "Execute a command",
  inputSchema: ExecuteCommandInput.self
) { input, _ in
  CommandResult(status: "Scheduled: \(input.command)")
}

Temperature Settings

For tool calls and object generation, it’s recommended to use temperature: 0 to ensure deterministic and consistent results:

import SwiftAISDK
import OpenAIProvider

let result = try await generateText(
  model: openai("gpt-4o"),
  temperature: 0, // Recommended for tool calls
  tools: ["myTool": executeCommand.tool],
  prompt: "Execute the ls command"
)

Using the executeCommand tool from above keeps the call deterministic while preserving the strongly typed schema.

Lower temperature values reduce randomness in model outputs, which is particularly important when the model needs to:

• Generate structured data with specific formats
• Make precise tool calls with correct parameters
• Follow strict schemas consistently

Debugging

Inspecting Warnings

Not all providers support all AI SDK features. Providers either throw exceptions or return warnings when they do not support a feature. To check if your prompt, tools, and settings are handled correctly by the provider, inspect the call warnings:

import SwiftAISDK
import OpenAIProvider

let result = try await generateText(
  model: openai("gpt-4o"),
  prompt: "Hello, world!"
)

print(result.warnings ?? [])

HTTP Request Bodies

You can inspect the raw HTTP request bodies for models that expose them, e.g. OpenAI. This allows you to inspect the exact payload that is sent to the model provider in the provider-specific way.

Request bodies are available via the request.body property of the response:

import SwiftAISDK
import OpenAIProvider

let result = try await generateText(
  model: openai("gpt-4o"),
  prompt: "Hello, world!"
)

print(String(describing: result.request.body))