# 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.

## Descriptions
- 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).

## Tool count & loading
- 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`).

## Tool design & orchestration
- 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.

## Safety
- 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.

## Sources
- https://developers.openai.com/api/docs/guides/function-calling
- https://developers.openai.com/api/docs/guides/structured-outputs
- https://developers.openai.com/api/docs/guides/tools-tool-search