tool-calling-principles

Tool-Calling Principles

Purpose

Tools are the agent's only way to read or change the world, and the model chooses and fills them using nothing but names, descriptions, and schemas. Good tools are few, coarse-grained, strictly typed, safe to retry, and return compact results with actionable errors. This skill gives the rules and templates for designing them.

Agent Protocol

Trigger

"tool calling", "function calling", "tool schema", "tool description", "wrong tool selected", "tool errors", "strict mode", "structured output".

Input Context

• The operations the agent needs and the underlying APIs.
• Side effects of each operation (read, reversible write, irreversible).
• Provider (Anthropic, OpenAI, other) and whether strict schema mode is available.
• Observed failure transcripts if debugging.

Output Artifact

Tool definitions (JSON Schema), handler skeletons with validation and error contract, permission matrix.

Response Format

Tool: {verb_noun}  Side effect: {read|write-reversible|write-irreversible}  Approval: {none|human}
Description: {what, when to use, when NOT to use, output shape, limits}
Schema: {required fields, enums, formats}
Errors: {code: hint}
Idempotency: {key or natural}

Completion Criteria

• Small, cohesive tool set; overlapping tools merged or removed.
• Descriptions say when to use and when not to use.
• Schemas use enums/formats/required fields; strict mode on where supported.
• Errors return code + message + corrective hint.
• Write tools idempotent; irreversible tools gated.

Design Rules

1. Name by intent: search_orders, refund_order, not api_call or execute.
2. Coarse over chatty: one get_customer_summary beats five getters the model must chain.
3. Descriptions are prompts: purpose, when to use, when not to, input semantics, output shape, limits (e.g. "returns at most 20 rows").
4. Constrain inputs: enum for categorical values, format/pattern for ids and dates, minimum/maximum for numbers, required for everything mandatory, additionalProperties: false.
5. Flat, primitive arguments: nested objects raise error rates; prefer start_date, end_date over {range: {...}}.
6. Compact outputs: return only fields the model needs; paginate with a cursor; cap size. Return the new state after a write ("refund R-91 created, status=pending"), not just true.
7. Errors that teach: {"error": "ORDER_NOT_FOUND", "message": "...", "hint": "use search_orders with the customer's email first"}.
8. Idempotency: write tools accept an idempotency key or are naturally idempotent (set, not increment).
9. Least privilege: separate read and write tools so read-only agents never see writes.
10. Never trust arguments: validate server-side; the schema is guidance to the model, not a security boundary.