namespace ColaFlow.Modules.Mcp.Contracts.Tools;

/// <summary>
/// Interface for MCP Tools
/// Tools provide write operations to AI agents through the MCP protocol
/// All write operations create PendingChanges and require human approval
/// </summary>
public interface IMcpTool
{
    /// <summary>
    /// Tool name (e.g., "create_issue", "update_status")
    /// Must be unique and follow snake_case naming convention
    /// </summary>
    string Name { get; }

    /// <summary>
    /// Human-readable tool description for AI to understand when to use this tool
    /// </summary>
    string Description { get; }

    /// <summary>
    /// JSON Schema describing the tool's input parameters
    /// </summary>
    McpToolInputSchema InputSchema { get; }

    /// <summary>
    /// Execute the tool with the provided arguments
    /// This should create a PendingChange, NOT execute the change directly
    /// </summary>
    /// <param name="toolCall">The tool call request with arguments</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>Tool execution result</returns>
    Task<McpToolResult> ExecuteAsync(
        McpToolCall toolCall,
        CancellationToken cancellationToken);

    /// <summary>
    /// Get tool descriptor with full metadata
    /// </summary>
    McpToolDescriptor GetDescriptor()
    {
        return new McpToolDescriptor
        {
            Name = Name,
            Description = Description,
            InputSchema = InputSchema
        };
    }
}
