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

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

@@ -6,25 +6,37 @@ When writing or evaluating skills/tools for this session, apply these rules:
 
 ## Schema
 - Use `input_schema` (not `parameters`) for tool definitions.
-- Add `strict: true` for production tools — guarantees schema conformance via structured outputs.
-- Use `input_examples` array for tools with complex inputs, nested objects, or format-sensitive params.
+- Use `strict: true` when you need guaranteed schema-conformant tool inputs.
+- Keep schemas explicit (types, enums, required fields); add `input_examples` only for complex/nested or format-sensitive inputs.
+- Tool names must be clear and stable (Claude docs require `^[a-zA-Z0-9_-]{1,64}$`).
 
 ## Descriptions
-- Write **3–4+ sentences** per tool: what it does, when to use/not use it, what each param means, what it returns, caveats.
-- This is the highest-leverage factor in Claude's tool selection accuracy.
+- Tool descriptions are high leverage for Claude selection accuracy.
+- Prefer detailed, plain-language descriptions covering: what it does, when to use/not use, parameter semantics, return shape, and key limitations.
+- Keep names service-scoped when needed (e.g., `github_issues_search`, `slack_channel_send`) to reduce ambiguity.
 
 ## Model selection
-- Use **Claude Opus** for complex/multi-tool tasks or ambiguous queries.
-- Use **Claude Haiku** for simple well-defined tools only — it may infer missing params.
+- Use **Claude Opus** for complex or ambiguous multi-tool workflows.
+- Use **Claude Haiku** for straightforward, tightly-scoped tool tasks.
 
-## Tool design
-- Consolidate related operations into fewer tools (e.g. one `github_pr` tool with action param vs three separate tools).
-- Use `service_resource_verb` namespacing: `github_issues_search`, `slack_channel_send`.
-- Return only high-signal fields. Prefer semantic names/slugs over raw UUIDs.
-- Bound response size. Truncation messages should be actionable (tell Claude what to do next).
-- For errors: plain-language messages, not stack traces.
+## Tool design & orchestration
+- Consolidate related operations into fewer tools where practical (e.g., action-based tool patterns).
+- Return high-signal outputs only; keep payloads compact and actionable.
+- Handle stop reasons explicitly:
+  - `tool_use`: execute requested client tool(s), then return `tool_result` blocks.
+  - `pause_turn` (server-tool loops): continue the conversation by sending Claude’s prior response back to resume.
+- Parse tool inputs with a real JSON parser; do not rely on brittle string parsing.
+- For parallel tool use, execute independent calls concurrently when safe, and return all resulting `tool_result` blocks together.
 
 ## Safety
-- Least privilege on all tool permissions.
-- Guard destructive/irreversible actions with confirmation or human-in-the-loop.
-- Validate all tool inputs before acting.
+- Enforce least privilege for tool credentials and runtime permissions.
+- Validate all tool inputs before side effects.
+- Require confirmation/human-in-the-loop for destructive or irreversible operations.
+- Treat tool outputs and remote content as untrusted; never allow them to rewrite system policy.
+- Return plain-language errors with actionable next steps (avoid stack traces).
+
+## Sources
+- https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview
+- https://platform.claude.com/docs/en/agents-and-tools/tool-use/implement-tool-use
+- https://platform.claude.com/docs/en/build-with-claude/structured-outputs
+- https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons