Tool Use & Function Calling Best Practices

Ten practices for naming, describing, scoping, validating, and operating tools so agents select them correctly and fail safely.

How to Use This List

• Use items 1-4 when designing or reviewing a tool surface (selection quality).
• Use items 5-7 when implementing the host loop (execution safety).
• Use items 8-10 in production ops and iteration (evidence and scale).
• Jump to deeper pages when an audit item fails; this list is a control checklist, not a full design doc.

1. Keep the tool list small and non-overlapping. Prefer a handful of sharp tools over a kitchen sink of near-duplicates. Merge tools that always run together; split opposite side effects. Overlap is the leading cause of wrong-tool calls. See Writing Tool Descriptions the Model Will Actually Use Correctly.

2. Name tools as clear verb_noun actions. Use get_order_status, create_refund, search_orders_by_email. Avoid vague names (helper, handle, data). Stable names are part of your public contract with prompts, evals, and MCP clients.

3. Write descriptions with triggers and non-goals. Lead with what the tool does and when to use it; add what it is not for and which sibling to use instead. Put shared policy in the system prompt; keep tool text local and scannable.

4. Constrain parameters with conservative JSON Schema. Root type: object, explicit required, enums for closed sets, bounds on numbers/arrays, and additionalProperties: false when supported. Validate the same rules in host code. See JSON Schema for Tool Parameters.

5. Remember: the model proposes, the host executes. Allowlist dispatch by name, authorize before side effects, and never eval free-form code from the model. Function calling is not a sandbox by itself. See How Function Calling Actually Works Under the Hood.

6. Return structured observations for success and failure. Use a uniform envelope (ok, data / error_type, retryable, short message). Always bind a tool result to each call id. Empty failures invite hallucinations. See Handling Tool Errors Gracefully Inside an Agent Loop.

7. Bound retries, parallelism, and run cost in the host. Cap max model turns, max tool calls, per-signature retries, concurrent executions, and result size. Disable or serialize parallel calls when tools write or share state. See Parallel Tool Calls.

8. Defer large catalogs with tool search. Keep a small always-on core; load full schemas on demand via search/retrieval. Do not treat hiding a write tool behind search as authorization. See Tool Search: Loading Tool Definitions On Demand.

9. Log trajectories with call ids, redacted args, and latency. Debug wrong selection, bad args, and slow upstreams from traces, not from final prose alone. Track wrong-tool rate and error-type histograms as product metrics.

10. Regression-test tool use with stubbed backends. Golden prompts should assert which tool is called, argument shapes, behavior on tool errors, and that read-only sessions cannot activate writes. Re-run the suite on every description or schema change.

FAQs

Related

• How Function Calling Actually Works Under the Hood
• Tool Use & Function Calling Basics
• Writing Tool Descriptions the Model Will Actually Use Correctly
• JSON Schema for Tool Parameters: A Reference Guide
• Parallel Tool Calls: When and How Models Call Multiple Tools at Once
• Tool Search: Loading Tool Definitions On Demand Instead of Upfront
• Handling Tool Errors Gracefully Inside an Agent Loop
• Agent Loop Best Practices
• Custom Tools Best Practices
• The Principle of Least Privilege Applied to Agent Tools

Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana @solana/web3.js + @solana/spl-token.