swarm-zap/skills/llm-tool-best-practices/hints/openai.md

MODEL_HINTS.md — OpenAI/GPT Tool Best Practices

Active model family: OpenAI (GPT)

When writing or evaluating skills/tools for this session, apply these rules:

Schema

• Use parameters (not input_schema) for tool definitions.
• Always set "strict": true — requires additionalProperties: false and all fields in required.
• For optional fields: add null to the type union (e.g. "type": ["string", "null"]) and keep in required.

Descriptions

• Write clear, detailed descriptions explaining purpose, each param, and output.
• Use the system prompt to describe when (and when NOT) to use each function.
• Do not add examples in descriptions for reasoning-capable GPT models — focus on clear prose.

Tool count & loading

• Keep initially available tools under ~20 for highest accuracy.
• Use defer_loading: true + tool search for large tool libraries — defer rarely-used tools.
• Use namespace type to group related tools by domain (e.g. crm, billing).

Tool design

• Use service_resource_verb namespacing: crm_customer_get, billing_invoice_list.
• Use enums and object structure to make invalid states unrepresentable.
• Combine functions always called in sequence into one tool.
• Don't ask the model to fill args you already know — pass them in code.

Parallel calls

• Parallel tool calls are on by default. Disable with parallel_tool_calls: false if tools have ordering dependencies.

Safety

• Use the Moderation API (free) to filter unsafe content.
• Pass safety_identifier (hashed user ID) with requests for abuse detection.
• Human-in-the-loop for high-stakes or irreversible tool actions.
• Guard against prompt injection from tool outputs.