"""
Validate required arguments for the getTime tool.

Demonstrates custom validation beyond simple required-field checking:
- Ensures at least one time source (timezone or city) is provided
- Validates timezone is in IANA format if specified
- Validates city name is not empty if specified

# Arguments
- `args::Dict{String,Any}`: Arguments from the LLM

# Returns
- `nothing` if validation passes
- `String` error message if validation fails
"""
function validateRequiredArgs(args::Dict{String,Any})::Union{Nothing,String}
    tz = get(args, "timezone", nothing)
    city = get(args, "city", "")
    
    hasTz = tz !== nothing && !isempty(tz)
    hasCity = !isempty(city)
    
    # At least one of timezone or city is required
    if !hasTz && !hasCity
        return "Missing required argument: provide at least one of 'timezone' or 'city'"
    end
    
    # Validate timezone format (IANA tz database: "Continent/City" or "Continent/City/SubCity")
    if hasTz
        tz_str = string(tz)
        if !occursin(r"^[A-Za-z]+\/[A-Za-z]+(/[A-Za-z]+)*$", tz_str)
            return "Invalid timezone format: '$tz_str'. Use IANA format, e.g. 'America/New_York' or 'Asia/Tokyo'"
        end
    end
    
    return nothing
end

"""
Execute the getTime tool.

# Arguments
- `toolCallId::String`: Unique identifier for this tool call
- `args::Dict{String,Any}`: Parsed arguments from the LLM
- `signal::Union{Nothing,abortSignal}`: Optional abort signal
- `onPartialResult::Function`: Callback for streaming partial results

# Returns
- `agentToolResult`: Result content with current time data
"""
function executeTool(toolCallId::String, args::Dict{String,Any}, signal::Union{Nothing,abortSignal}, onPartialResult::Function)::agentToolResult
    tz = get(args, "timezone", nothing)
    city = get(args, "city", "")
    
    # Simulate time lookup — replace with actual timezone API call
    if tz !== nothing
        result = "Current time in $(tz): $(now())"
    else
        result = "Current time in $(city): $(now())"
    end
    
    return agentToolResult(
        [textContent(result)],
        Dict{Any,Any}(), nothing, false
    )
end

"""
Define and return the getTime agentTool.
"""
function getTool()::agentTool
    return agentTool(
        name = "getTime",
        label = "Time Lookup",
        description = "Get current local time for a timezone or city.",
        inputSchema = Dict{String,Any}(
            "type" => "object",
            "properties" => Dict(
                "timezone" => Dict("type" => "string", "description", "IANA timezone, e.g. 'America/New_York'"),
                "city" => Dict("type" => "string", "description", "City name as fallback")
            ),
            "required" => []
        ),
        execute = executeTool,
        prepareArguments = nothing,
        validateRequiredArgs = validateRequiredArgs,
        parallelToolExecute = false
    )
end