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 function tools.
Set "strict": true for production tools.
With strict mode, every object must set additionalProperties: false.
With strict mode, all declared properties must be listed in required.
Represent optional fields as nullable unions (e.g., "type": ["string", "null"]) while still keeping them in required.
Prefer enums, bounded arrays, and nested object structure to make invalid states hard to express.

Write clear, implementation-level descriptions for the tool and each parameter (including units/formats).
In system/developer instructions, state when to use each tool and when not to.
For reasoning-capable models, prefer concise prose over long in-schema examples (add examples only when they fix recurring failures).

Keep initially available tools small (soft target: <20).
For large tool surfaces, use defer_loading: true with tool search.
Use type: "namespace" to group related tools by domain (e.g., crm, billing).

Use stable service_resource_verb naming (e.g., billing_invoice_list).
Don’t ask the model for arguments your app already knows; inject them in code.
Merge tools that are always called together.
Assume the model may return multiple function_call items in one turn; execute each and return matching function_call_output by call_id.
For reasoning models, pass reasoning items from prior response back alongside tool outputs on the next turn.
Use tool_choice deliberately (auto, required, forced function, or allowed_tools subset).
Disable parallel calls (parallel_tool_calls: false) when operations must be strictly ordered.

Validate tool-call arguments server-side before execution (types, authZ, business constraints).
Treat tool output as untrusted input; never let tool text override policy/instructions.
Require confirmation or human approval for destructive/irreversible actions.
Use moderation/guardrails on user content when domain risk warrants it.
Use user-level abuse correlation identifiers (e.g., safety_identifier) where available.