tool-use-and-function-calling

Tool Use and Function Calling

Purpose: Build LLM agents that call tools reliably with correct arguments, handle failures gracefully, and produce structured results.

---

When to Use This Skill

• Designing tools / functions an agent will call
• Defining JSON schemas for tool arguments and structured outputs
• Enabling and tuning parallel tool calls
• Designing tool error contracts and retries
• Building MCP tools (see also mcp-server-development)

---

Tool Design Principles

Principle	Rule
Single responsibility	One tool = one verb-phrase action
Strict typing	JSON Schema with required, types, enum, pattern
Idempotent where possible	Safe to retry on transient failure
Stateless arguments	All inputs in args -- no hidden context
Bounded outputs	Cap response size; truncate large lists with pagination tokens
Errors as data	Return { ok: false, error: { code, message, retryable } }, do not throw

---

Schema Quality Checklist

• description on every tool and every parameter
• required array lists ONLY truly required params
• Use enum for fixed value sets (not free-form strings)
• Use pattern for IDs / SKUs / formatted strings
• Avoid deeply nested objects (>3 levels) -- flatten
• Avoid oneOf / anyOf at the top level (model selection accuracy drops)
• Document units (seconds vs ms, USD vs cents)
• Set additionalProperties: false to catch hallucinated fields

---

Parallel Tool Calls

Current models (GPT-6 Astra, Claude Opus 5.5, Gemini) emit multiple tool calls in one turn. Astra tool calling needs the Responses API; Opus 5.5 rejects forced tool_choice (any or a named tool), so steer with descriptions and prompts.

• MUST run independent calls concurrently (asyncio / Promise.all / Task.WhenAll)
• MUST preserve tool_call_id -> result mapping
• MUST handle partial failures: return per-call results, do not fail the batch
• SHOULD set a wall-clock timeout per batch
• SHOULD disable parallel calls when ordering matters (use parallel_tool_calls: false)