chore(model-hints): sync OpenAI and Anthropic best-practice guidance

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

@@ -5,31 +5,40 @@ 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`.
+- 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, 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.
+- 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 **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`).
+- 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
-- 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.
+## 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
-- 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.
+- 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