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