Define a Tool for Claude Tool Use

Claude's tool use (equivalent to OpenAI's function calling) enables the model to request specific data or actions from your application during a conversation. When Claude needs information it doesn't have — like current stock prices, database records, or the results of a calculation — it returns a tool_use block specifying which tool to call and with what parameters. Your application executes the tool and returns the result, which Claude then incorporates into its final response. This example defines a database search tool that Claude can use to look up customer records. The tool definition uses JSON Schema for the input_schema, just like OpenAI function calling. Key differences from OpenAI: the definition goes in the tools array at the top level of the request, and the tool result is returned in a separate user message with role "user" and a tool_result content block (not a "tool" role like OpenAI uses). For production tool use, write tool descriptions as if explaining to a human what each tool does and when to use it. Claude uses the description to decide whether to call the tool, so vague descriptions lead to incorrect tool selection. Be specific: "Search the customer database by email address or customer ID to retrieve account details, subscription status, and support history" is far more useful than "Look up customer information".

{
  "model": "claude-3-5-sonnet-20241022",
  "max_tokens": 1024,
  "tools": [
    {
      "name": "search_customer_db",
      "description": "Search the customer database by email or customer ID to retrieve account details, subscription tier, creation date, and recent activity",
      "input_schema": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "description": "Email address or customer ID (format: CUST-XXXXXX)"
          },
          "fields": {
            "type": "array",
            "items": {"type": "string"},
            "description": "Specific fields to return. Leave empty for all fields."
          }
        },
        "required": ["query"]
      }
    }
  ],
  "messages": [
    {"role": "user", "content": "Can you look up the account for customer ID CUST-004821?"}
  ]
}